/ Hex Artifact Content
Login

Artifact 5c89ff33315006449119b86b460e0a286758f126:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
23f0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2400: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2410: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
2420: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2430: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
2440: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
2450: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2460: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
2470: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2480: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2490: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
24a0: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
24b0: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
24c0: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
24d0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
24e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24f0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2500: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2510: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
2520: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
2530: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
2540: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
2550: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
2560: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
2570: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2580: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2590: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
25a0: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
25b0: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
25c0: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
25d0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
25e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25f0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2600: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2610: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
2620: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
2630: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
2640: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2650: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
2660: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
2670: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2680: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2690: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26a0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26b0: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
26c0: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
26d0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
26e0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
26f0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2700: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2710: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
2720: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
2730: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2740: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
2750: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2760: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
2770: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2780: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2790: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
27a0: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
27b0: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
27c0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
27e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
27f0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2800: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2810: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
2820: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2830: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2840: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2850: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2860: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2870: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2890: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
28a0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
28b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
28c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
28d0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
28e0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2900: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2910: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2920: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2930: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2940: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2950: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2960: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2970: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2980: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2990: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
29a0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
29b0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
29c0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
29d0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
29e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
29f0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2a00: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2a10: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2a20: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
2a30: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2a40: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2a50: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
2a60: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
2a70: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
2a80: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
2a90: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
2aa0: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
2ab0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2ac0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
2ad0: 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71  K] if.** the [sq
2ae0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73  lite3] object is
2af0: 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65   successfully de
2b00: 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20  stroyed and all 
2b10: 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65  associated.** re
2b20: 73 6f 75 72 63 65 73 20 61 72 65 20 64 65 61 6c  sources are deal
2b30: 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  located..**.** ^
2b40: 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
2b50: 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73  connection is as
2b60: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 75 6e  sociated with un
2b70: 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72  finalized prepar
2b80: 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73  ed.** statements
2b90: 20 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73   or unfinished s
2ba0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62  qlite3_backup ob
2bb0: 6a 65 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74  jects then sqlit
2bc0: 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69  e3_close().** wi
2bd0: 6c 6c 20 6c 65 61 76 65 20 74 68 65 20 64 61 74  ll leave the dat
2be0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2bf0: 20 6f 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e   open and return
2c00: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a   [SQLITE_BUSY]..
2c10: 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  ** ^If sqlite3_c
2c20: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c  lose_v2() is cal
2c30: 6c 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c  led with unfinal
2c40: 69 7a 65 64 20 70 72 65 70 61 72 65 64 20 73 74  ized prepared st
2c50: 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f  atements.** and/
2c60: 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71  or unfinished sq
2c70: 6c 69 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74  lite3_backups, t
2c80: 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
2c90: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f   connection beco
2ca0: 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62  mes.** an unusab
2cb0: 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63  le "zombie" whic
2cc0: 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  h will automatic
2cd0: 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61  ally be dealloca
2ce0: 74 65 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20  ted when the.** 
2cf0: 6c 61 73 74 20 70 72 65 70 61 72 65 64 20 73 74  last prepared st
2d00: 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c  atement is final
2d10: 69 7a 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74  ized or the last
2d20: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20   sqlite3_backup 
2d30: 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20  is.** finished. 
2d40: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f   The sqlite3_clo
2d50: 73 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  se_v2() interfac
2d60: 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f  e is intended fo
2d70: 72 20 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f  r use with.** ho
2d80: 73 74 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61  st languages tha
2d90: 74 20 61 72 65 20 67 61 72 62 61 67 65 20 63 6f  t are garbage co
2da0: 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65  llected, and whe
2db0: 72 65 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20  re the order in 
2dc0: 77 68 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63  which.** destruc
2dd0: 74 6f 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20  tors are called 
2de0: 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a  is arbitrary..**
2df0: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
2e00: 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33   should [sqlite3
2e10: 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
2e20: 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61  lize] all [prepa
2e30: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c  red statements],
2e40: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
2e50: 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d  b_close | close]
2e60: 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c   all [BLOB handl
2e70: 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  es], and .** [sq
2e80: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e  lite3_backup_fin
2e90: 69 73 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c  ish | finish] al
2ea0: 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  l [sqlite3_backu
2eb0: 70 5d 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63  p] objects assoc
2ec0: 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  iated.** with th
2ed0: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
2ee0: 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65  ct prior to atte
2ef0: 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20  mpting to close 
2f00: 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66  the object.  ^If
2f10: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  .** sqlite3_clos
2f20: 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  e_v2() is called
2f30: 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20   on a [database 
2f40: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
2f50: 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75   still has.** ou
2f60: 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61  tstanding [prepa
2f70: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c  red statements],
2f80: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c   [BLOB handles],
2f90: 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69   and/or.** [sqli
2fa0: 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65  te3_backup] obje
2fb0: 63 74 73 20 74 68 65 6e 20 69 74 20 72 65 74 75  cts then it retu
2fc0: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
2fd0: 61 6e 64 20 74 68 65 20 64 65 61 6c 6c 6f 63 61  and the dealloca
2fe0: 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75  tion.** of resou
2ff0: 72 63 65 73 20 69 73 20 64 65 66 65 72 72 65 64  rces is deferred
3000: 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70   until all [prep
3010: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
3020: 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d  , [BLOB handles]
3030: 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ,.** and [sqlite
3040: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
3050: 73 20 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72  s are also destr
3060: 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  oyed..**.** ^If 
3070: 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  an [sqlite3] obj
3080: 65 63 74 20 69 73 20 64 65 73 74 72 6f 79 65 64  ect is destroyed
3090: 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63   while a transac
30a0: 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a  tion is open,.**
30b0: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
30c0: 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
30d0: 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
30e0: 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d  *.** The C param
30f0: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
3100: 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b  _close(C)] and [
3110: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
3120: 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20  (C)].** must be 
3130: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a  either a NULL.**
3140: 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b   pointer or an [
3150: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
3160: 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64  pointer obtained
3170: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3180: 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
3190: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f  te3_open16()], o
31a0: 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
31b0: 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f  en_v2()], and no
31c0: 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f  t previously clo
31d0: 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  sed..** ^Calling
31e0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
31f0: 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73   or sqlite3_clos
3200: 65 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e 55  e_v2() with a NU
3210: 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72  LL pointer.** ar
3220: 67 75 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d  gument is a harm
3230: 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69  less no-op..*/.i
3240: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
3250: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69 6e 74 20  (sqlite3*);.int 
3260: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
3270: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
3280: 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20  ** The type for 
3290: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
32a0: 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ion..** This is 
32b0: 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65  legacy and depre
32c0: 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e  cated.  It is in
32d0: 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f  cluded for histo
32e0: 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69  rical.** compati
32f0: 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f  bility and is no
3300: 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f  t documented..*/
3310: 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73  .typedef int (*s
3320: 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29  qlite3_callback)
3330: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
3340: 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a  *, char**);../*.
3350: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65  ** CAPI3REF: One
3360: 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63  -Step Query Exec
3370: 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a  ution Interface.
3380: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
3390: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
33a0: 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65  ce is a convenie
33b0: 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f 75  nce wrapper arou
33c0: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  nd.** [sqlite3_p
33d0: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73  repare_v2()], [s
33e0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
33f0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  and [sqlite3_fin
3400: 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61  alize()],.** tha
3410: 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c  t allows an appl
3420: 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d  ication to run m
3430: 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65 6e  ultiple statemen
3440: 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74  ts of SQL.** wit
3450: 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20 75  hout having to u
3460: 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f  se a lot of C co
3470: 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de. .**.** ^The 
3480: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3490: 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a 65  nterface runs ze
34a0: 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38  ro or more UTF-8
34b0: 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d   encoded,.** sem
34c0: 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20  icolon-separate 
34d0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70  SQL statements p
34e0: 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20 32  assed into its 2
34f0: 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20  nd argument,.** 
3500: 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f  in the context o
3510: 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
3520: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73  connection] pass
3530: 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 73 74  ed in as its 1st
3540: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e  .** argument.  ^
3550: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
3560: 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65 20  function of the 
3570: 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  3rd argument to.
3580: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3590: 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  ) is not NULL, t
35a0: 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  hen it is invoke
35b0: 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 75 6c  d for each resul
35c0: 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20  t row.** coming 
35d0: 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c 75  out of the evalu
35e0: 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
35f0: 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20 61  nts.  ^The 4th a
3600: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
3610: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3620: 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68 20  relayed through 
3630: 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75 6d  to the 1st argum
3640: 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63  ent of each.** c
3650: 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74 69  allback invocati
3660: 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  on.  ^If the cal
3670: 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f  lback pointer to
3680: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3690: 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ** is NULL, then
36a0: 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73 20   no callback is 
36b0: 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64  ever invoked and
36c0: 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72 65   result rows are
36d0: 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  .** ignored..**.
36e0: 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20  ** ^If an error 
36f0: 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76 61  occurs while eva
3700: 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20  luating the SQL 
3710: 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65  statements passe
3720: 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  d into.** sqlite
3730: 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20 65  3_exec(), then e
3740: 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20  xecution of the 
3750: 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65 6e  current statemen
3760: 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73  t stops and.** s
3770: 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65 6d  ubsequent statem
3780: 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65 64  ents are skipped
3790: 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  .  ^If the 5th p
37a0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
37b0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
37c0: 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61   not NULL then a
37d0: 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  ny error message
37e0: 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
37f0: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
3800: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3810: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
3820: 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f  passed back thro
3830: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
3840: 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f  meter..** To avo
3850: 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c  id memory leaks,
3860: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
3870: 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b   should invoke [
3880: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a  sqlite3_free()].
3890: 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73  ** on error mess
38a0: 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  age strings retu
38b0: 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68 65  rned through the
38c0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f   5th parameter o
38d0: 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  f.** of sqlite3_
38e0: 65 78 65 63 28 29 20 61 66 74 65 72 20 74 68 65  exec() after the
38f0: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3900: 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67  tring is no long
3910: 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49  er needed..** ^I
3920: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3930: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3940: 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  xec() is not NUL
3950: 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a  L and no errors.
3960: 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73  ** occur, then s
3970: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 73 65  qlite3_exec() se
3980: 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69  ts the pointer i
3990: 6e 20 69 74 73 20 35 74 68 20 70 61 72 61 6d 65  n its 5th parame
39a0: 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62  ter to.** NULL b
39b0: 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
39c0: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71  .**.** ^If an sq
39d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
39e0: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
39f0: 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69  n-zero, the sqli
3a00: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f  te3_exec().** ro
3a10: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51  utine returns SQ
3a20: 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f  LITE_ABORT witho
3a30: 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  ut invoking the 
3a40: 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61  callback again a
3a50: 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75  nd.** without ru
3a60: 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71  nning any subseq
3a70: 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65  uent SQL stateme
3a80: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
3a90: 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  2nd argument to 
3aa0: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
3ab0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  () callback func
3ac0: 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e  tion is the.** n
3ad0: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
3ae0: 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20   in the result. 
3af0: 20 5e 54 68 65 20 33 72 64 20 61 72 67 75 6d 65   ^The 3rd argume
3b00: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
3b10: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c  3_exec().** call
3b20: 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79  back is an array
3b30: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
3b40: 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64  strings obtained
3b50: 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b   as if from.** [
3b60: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
3b70: 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20  ext()], one for 
3b80: 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49  each column.  ^I
3b90: 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20  f an element of 
3ba0: 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  a.** result row 
3bb0: 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
3bc0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73   corresponding s
3bd0: 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f  tring pointer fo
3be0: 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  r the.** sqlite3
3bf0: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3c00: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
3c10: 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72  er.  ^The 4th ar
3c20: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a  gument to the.**
3c30: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3c40: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61  callback is an a
3c50: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
3c60: 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72   to strings wher
3c70: 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20  e each.** entry 
3c80: 72 65 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e  represents the n
3c90: 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e  ame of correspon
3ca0: 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75  ding result colu
3cb0: 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mn as obtained.*
3cc0: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
3cd0: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a  column_name()]..
3ce0: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e  **.** ^If the 2n
3cf0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
3d00: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3d10: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
3d20: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
3d30: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
3d40: 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74  , or a pointer t
3d50: 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c  hat contains onl
3d60: 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64  y whitespace and
3d70: 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d  /or .** SQL comm
3d80: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51  ents, then no SQ
3d90: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
3da0: 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74   evaluated and t
3db0: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  he database.** i
3dc0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a  s not changed..*
3dd0: 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e  *.** Restriction
3de0: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
3df0: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3e00: 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73 75 72  ation must insur
3e10: 65 20 74 68 61 74 20 74 68 65 20 31 73 74 20 70  e that the 1st p
3e20: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3e30: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20  te3_exec().**   
3e40: 20 20 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e     is a valid an
3e50: 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  d open [database
3e60: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
3e70: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3e80: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63  ation must not c
3e90: 6c 6f 73 65 20 74 68 65 20 5b 64 61 74 61 62 61  lose the [databa
3ea0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
3eb0: 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20  pecified by.**  
3ec0: 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72 61      the 1st para
3ed0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
3ee0: 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71  _exec() while sq
3ef0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3f00: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e  running..** <li>
3f10: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
3f20: 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79   must not modify
3f30: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
3f40: 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20 69  nt text passed i
3f50: 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20  nto.**      the 
3f60: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
3f70: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3f80: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78  while sqlite3_ex
3f90: 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ec() is running.
3fa0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74  .** </ul>.*/.int
3fb0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20   sqlite3_exec(. 
3fc0: 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20   sqlite3*,      
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fe0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
3ff0: 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
4000: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
4010: 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20  *sql,           
4020: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4030: 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
4040: 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20  luated */.  int 
4050: 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  (*callback)(void
4060: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61  *,int,char**,cha
4070: 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61  r**),  /* Callba
4080: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  ck function */. 
4090: 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20   void *,        
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31              /* 1
40c0: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  st argument to c
40d0: 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61  allback */.  cha
40e0: 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20  r **errmsg      
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4100: 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72          /* Error
4110: 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
4120: 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
4130: 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
4140: 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Codes.** KEYWORD
4150: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20  S: {result code 
4160: 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a  definitions}.**.
4170: 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66  ** Many SQLite f
4180: 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
4190: 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c  an integer resul
41a0: 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20  t code from the 
41b0: 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72  set shown.** her
41c0: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  e in order to in
41d0: 64 69 63 61 74 65 20 73 75 63 63 65 73 73 20 6f  dicate success o
41e0: 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  r failure..**.**
41f0: 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73   New error codes
4200: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
4210: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
4220: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
4230: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74  * See also: [ext
4240: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4250: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a  e definitions].*
4260: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4270: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
4280: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
4290: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
42a0: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
42b0: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
42c0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
42d0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
42e0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
42f0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
4300: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
4310: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
4320: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
4330: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
4340: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4350: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
4360: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
4370: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
4380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4390: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
43a0: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
43b0: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
43c0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
43d0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
43e0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
43f0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
4400: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
4410: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4420: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4430: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4440: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4450: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4460: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4470: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
4480: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
4490: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
44a0: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
44b0: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
44c0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
44d0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
44e0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
44f0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
4500: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
4510: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4520: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4530: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4540: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4550: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4560: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4570: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4580: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4590: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
45a0: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
45b0: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
45c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
45d0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
45e0: 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65  * Unknown opcode
45f0: 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65   in sqlite3_file
4600: 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64  _control() */.#d
4610: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c  efine SQLITE_FUL
4620: 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a  L        13   /*
4630: 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65   Insertion faile
4640: 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61  d because databa
4650: 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64  se is full */.#d
4660: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
4670: 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a  TOPEN    14   /*
4680: 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20   Unable to open 
4690: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
46a0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
46b0: 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20  ITE_PROTOCOL    
46c0: 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  15   /* Database
46d0: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65   lock protocol e
46e0: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
46f0: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20  SQLITE_EMPTY    
4700: 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62     16   /* Datab
4710: 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a  ase is empty */.
4720: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
4730: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20  CHEMA      17   
4740: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
4750: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a  schema changed *
4760: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4770: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20  _TOOBIG      18 
4780: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42    /* String or B
4790: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65  LOB exceeds size
47a0: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e   limit */.#defin
47b0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
47c0: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f  INT  19   /* Abo
47d0: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72  rt due to constr
47e0: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a  aint violation *
47f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4800: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20  _MISMATCH    20 
4810: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d    /* Data type m
4820: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69  ismatch */.#defi
4830: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  ne SQLITE_MISUSE
4840: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69        21   /* Li
4850: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72  brary used incor
4860: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  rectly */.#defin
4870: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20  e SQLITE_NOLFS  
4880: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65       22   /* Use
4890: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f  s OS features no
48a0: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68  t supported on h
48b0: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ost */.#define S
48c0: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20  QLITE_AUTH      
48d0: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72    23   /* Author
48e0: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a  ization denied *
48f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4900: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20  _FORMAT      24 
4910: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64    /* Auxiliary d
4920: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65  atabase format e
4930: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4940: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4950: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4960: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4970: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
4980: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
4990: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
49a0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
49b0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
49c0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
49d0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
49e0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20  QLITE_NOTICE    
49f0: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69    27   /* Notifi
4a00: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c  cations from sql
4a10: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
4a30: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a  NING     28   /*
4a40: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73   Warnings from s
4a50: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
4a60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4a70: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
4a80: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4a90: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
4aa0: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
4ab0: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
4ac0: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
4ad0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4ae0: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
4af0: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
4b00: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4b10: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4b20: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
4b30: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
4b40: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4b50: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4b60: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  tions}.**.** In 
4b70: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4b80: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4b90: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4ba0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20  eturn one of 30 
4bb0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75  integer.** [resu
4bc0: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
4bd0: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
4be0: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d  has shown that m
4bf0: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  any of.** these 
4c00: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4c10: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69   too coarse-grai
4c20: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
4c30: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
4c40: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
4c50: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
4c60: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
4c70: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
4c80: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
4c90: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
4ca0: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
4cb0: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
4cc0: 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20  .3.8 and later) 
4cd0: 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f  include.** suppo
4ce0: 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rt for additiona
4cf0: 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74  l result codes t
4d00: 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65  hat provide more
4d10: 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d   detailed inform
4d20: 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65  ation.** about e
4d30: 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b 65 78  rrors. These [ex
4d40: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4d50: 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64  des] are enabled
4d60: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4d70: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4d80: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
4d90: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
4da0: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
4db0: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
4dc0: 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 65 20  ] API.  Or, the 
4dd0: 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20 66 6f  extended code fo
4de0: 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65  r.** the most re
4df0: 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e 20 62  cent error can b
4e00: 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e 67  e obtained using
4e10: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
4e20: 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d  ended_errcode()]
4e30: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
4e40: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
4e50: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4e60: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
4e70: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e80: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
4e90: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
4ea0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
4eb0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4ec0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
4ed0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4ee0: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
4ef0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4f00: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
4f10: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4f20: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
4f30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4f40: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
4f50: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4f60: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
4f70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4f80: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
4f90: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4fa0: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
4fb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4fc0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
4fd0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4fe0: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
4ff0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5000: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5010: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5020: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
5030: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5040: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5050: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5060: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
5070: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5080: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
5090: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
50a0: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
50b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
50c0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
50d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
50e0: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
50f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5100: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5110: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5120: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
5130: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5140: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5150: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5160: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
5170: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5180: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
5190: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
51a0: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
51b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
51c0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
51d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
51e0: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
51f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5200: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5210: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5220: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
5230: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5240: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5250: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5260: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
5270: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5280: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
5290: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52a0: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
52b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52c0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
52d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52e0: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
52f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5300: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5310: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5320: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5330: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5340: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5350: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5360: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5370: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5380: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
5390: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53a0: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
53b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53c0: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
53d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53e0: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
53f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5400: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
5410: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5420: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
5430: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5440: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
5450: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5460: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
5470: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5480: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
5490: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54a0: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
54b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
54c0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
54d0: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
54e0: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
54f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5500: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5510: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5520: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5530: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5540: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
5550: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5560: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
5570: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5580: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5590: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
55a0: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
55b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55c0: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
55d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
55e0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
55f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5600: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
5610: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
5620: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
5630: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5640: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
5650: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
5660: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5670: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5680: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
5690: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
56a0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
56b0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
56c0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
56d0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
56e0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
56f0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5700: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5710: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
5720: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5730: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
5740: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5750: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  NLY_ROLLBACK    
5760: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5770: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  NLY | (3<<8)).#d
5780: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5790: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20  DONLY_DBMOVED   
57a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
57b0: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a  DONLY | (4<<8)).
57c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
57d0: 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20  BORT_ROLLBACK   
57e0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41         (SQLITE_A
57f0: 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23  BORT | (2<<8)).#
5800: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5810: 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20  NSTRAINT_CHECK  
5820: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5830: 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38  NSTRAINT | (1<<8
5840: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5850: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d  E_CONSTRAINT_COM
5860: 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54  MITHOOK   (SQLIT
5870: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5880: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5890: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
58a0: 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53  _FOREIGNKEY   (S
58b0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
58c0: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
58d0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
58e0: 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20  AINT_FUNCTION   
58f0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5900: 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23  AINT | (4<<8)).#
5910: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5920: 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c  NSTRAINT_NOTNULL
5930: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5940: 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38  NSTRAINT | (5<<8
5950: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5960: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49  E_CONSTRAINT_PRI
5970: 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54  MARYKEY   (SQLIT
5980: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5990: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
59a0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
59b0: 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53  _TRIGGER      (S
59c0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
59d0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
59e0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
59f0: 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20  AINT_UNIQUE     
5a00: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5a10: 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23  AINT | (8<<8)).#
5a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5a30: 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20  NSTRAINT_VTAB   
5a40: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5a50: 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38  NSTRAINT | (9<<8
5a60: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5a70: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57  E_CONSTRAINT_ROW
5a80: 49 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  ID        (SQLIT
5a90: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31  E_CONSTRAINT |(1
5aa0: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
5ab0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5ac0: 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53  OVER_WAL      (S
5ad0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5ae0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5af0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5b00: 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53  OVER_ROLLBACK (S
5b10: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5b20: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5b30: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55  QLITE_WARNING_AU
5b40: 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53  TOINDEX       (S
5b50: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20  QLITE_WARNING | 
5b60: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5b70: 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53 45 52  SQLITE_AUTH_USER
5b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28                 (
5b90: 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20 28 31  SQLITE_AUTH | (1
5ba0: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  <<8))../*.** CAP
5bb0: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72  I3REF: Flags For
5bc0: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61   File Open Opera
5bd0: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
5be0: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65  e bit values are
5bf0: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
5c00: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20  e in the.** 3rd 
5c10: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
5c20: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
5c30: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  2()] interface a
5c40: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68  nd.** in the 4th
5c50: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
5c60: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
5c70: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f  Open] method..*/
5c80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c90: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
5ca0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
5cb0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5cc0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5cd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ce0: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
5cf0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
5d00: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5d10: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5d20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d30: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
5d40: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
5d50: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5d60: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5d70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d80: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
5d90: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
5da0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5db0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5dc0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
5dd0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
5de0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5df0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e00: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20  OPEN_AUTOPROXY  
5e10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
5e20: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5e30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e40: 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20  OPEN_URI        
5e50: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
5e60: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5e70: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5e80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e90: 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20  OPEN_MEMORY     
5ea0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
5eb0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5ec0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5ed0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ee0: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
5ef0: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
5f00: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5f10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5f20: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
5f30: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
5f40: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5f50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5f60: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
5f70: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
5f80: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5f90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5fa0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
5fb0: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
5fc0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5fd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5fe0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
5ff0: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
6000: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6010: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6020: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
6030: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
6040: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6050: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6060: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
6070: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
6080: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6090: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
60a0: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20  OPEN_NOMUTEX    
60b0: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30        0x00008000
60c0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
60d0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
60e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
60f0: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20  OPEN_FULLMUTEX  
6100: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30        0x00010000
6110: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6120: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6130: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6140: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
6150: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30        0x00020000
6160: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6170: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6180: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6190: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
61a0: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30  E     0x00040000
61b0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
61c0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
61d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
61e0: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20  OPEN_WAL        
61f0: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30        0x00080000
6200: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6210: 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20  ../* Reserved:  
6220: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6230: 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30         0x00F0000
6240: 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0 */../*.** CAPI
6250: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
6260: 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a  racteristics.**.
6270: 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68  ** The xDeviceCh
6280: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65  aracteristics me
6290: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c  thod of the [sql
62a0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
62b0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72  .** object retur
62c0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  ns an integer wh
62d0: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20  ich is a vector 
62e0: 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20  of these.** bit 
62f0: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e  values expressin
6300: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69  g I/O characteri
6310: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73  stics of the mas
6320: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76  s storage.** dev
6330: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74  ice that holds t
6340: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65  he file that the
6350: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6360: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20  hods].** refers 
6370: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  to..**.** The SQ
6380: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6390: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
63a0: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
63b0: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
63c0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
63d0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
63e0: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
63f0: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
6400: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
6410: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
6420: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
6430: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
6440: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
6450: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
6460: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
6470: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
6480: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
6490: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
64a0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
64b0: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
64c0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
64d0: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
64e0: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
64f0: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
6500: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
6510: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
6520: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
6530: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
6540: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
6550: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
6560: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
6570: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
6580: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
6590: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
65a0: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
65b0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
65c0: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
65d0: 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20  RWRITE property 
65e0: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66  means that.** af
65f0: 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f  ter reboot follo
6600: 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20  wing a crash or 
6610: 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20  power loss, the 
6620: 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a  only bytes in a.
6630: 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72  ** file that wer
6640: 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65  e written at the
6650: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76   application lev
6660: 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68  el might have ch
6670: 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61  anged.** and tha
6680: 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73  t adjacent bytes
6690: 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74  , even bytes wit
66a0: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63  hin the same sec
66b0: 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61  tor are.** guara
66c0: 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68  nteed to be unch
66d0: 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49  anged.  The SQLI
66e0: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
66f0: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a  ABLE_WHEN_OPEN.*
6700: 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 20  * flag indicate 
6710: 74 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e 6e  that a file cann
6720: 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20 77 68  ot be deleted wh
6730: 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a  en open.  The.**
6740: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d   SQLITE_IOCAP_IM
6750: 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69 6e 64  MUTABLE flag ind
6760: 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20  icates that the 
6770: 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65  file is on.** re
6780: 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e  ad-only media an
6790: 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e  d cannot be chan
67a0: 67 65 64 20 65 76 65 6e 20 62 79 20 70 72 6f 63  ged even by proc
67b0: 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c  esses with.** el
67c0: 65 76 61 74 65 64 20 70 72 69 76 69 6c 65 67 65  evated privilege
67d0: 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s..*/.#define SQ
67e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
67f0: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  C               
6800: 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65    0x00000001.#de
6810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6820: 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20  P_ATOMIC512     
6830: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6840: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
6850: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
6860: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
6870: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69  0x00000004.#defi
6880: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6890: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20  ATOMIC2K        
68a0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
68b0: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
68c0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20  _IOCAP_ATOMIC4K 
68d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
68e0: 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65  00000010.#define
68f0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6900: 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 20  OMIC8K          
6910: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a       0x00000020.
6920: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6930: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20  OCAP_ATOMIC16K  
6940: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6950: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53  000040.#define S
6960: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6970: 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 20  IC32K           
6980: 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64     0x00000080.#d
6990: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
69a0: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20  AP_ATOMIC64K    
69b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
69c0: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0100.#define SQL
69d0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
69e0: 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 20  PPEND           
69f0: 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66   0x00000200.#def
6a00: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6a10: 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20  _SEQUENTIAL     
6a20: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 34          0x000004
6a30: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6a40: 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41  E_IOCAP_UNDELETA
6a50: 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30  BLE_WHEN_OPEN  0
6a60: 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e  x00000800.#defin
6a70: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50  e SQLITE_IOCAP_P
6a80: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
6a90: 54 45 20 20 20 20 30 78 30 30 30 30 31 30 30 30  TE    0x00001000
6aa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6ab0: 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20  IOCAP_IMMUTABLE 
6ac0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6ad0: 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0002000../*.** C
6ae0: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
6af0: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a  cking Levels.**.
6b00: 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f  ** SQLite uses o
6b10: 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
6b20: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
6b30: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75  e second.** argu
6b40: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74  ment to calls it
6b50: 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c   makes to the xL
6b60: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
6b70: 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  k() methods.** o
6b80: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  f an [sqlite3_io
6b90: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
6ba0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
6bb0: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20  ITE_LOCK_NONE   
6bc0: 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
6bd0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41   SQLITE_LOCK_SHA
6be0: 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65  RED        1.#de
6bf0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6c00: 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32  _RESERVED      2
6c10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6c20: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20  LOCK_PENDING    
6c30: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
6c40: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
6c50: 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20  VE     4../*.** 
6c60: 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72  CAPI3REF: Synchr
6c70: 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46  onization Type F
6c80: 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  lags.**.** When 
6c90: 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74  SQLite invokes t
6ca0: 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f  he xSync() metho
6cb0: 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  d of an.** [sqli
6cc0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6cd0: 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61  object it uses a
6ce0: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a   combination of.
6cf0: 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  ** these integer
6d00: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
6d10: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  econd argument..
6d20: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53  **.** When the S
6d30: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
6d40: 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64  NLY flag is used
6d50: 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
6d60: 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72  the.** sync oper
6d70: 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73  ation only needs
6d80: 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74   to flush data t
6d90: 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20  o mass storage. 
6da0: 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d   Inode.** inform
6db0: 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62  ation need not b
6dc0: 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68  e flushed. If th
6dd0: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
6de0: 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a  s of the flag.**
6df0: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
6e00: 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20  NC_NORMAL, that 
6e10: 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72  means to use nor
6e20: 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61  mal fsync() sema
6e30: 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65  ntics..** If the
6e40: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
6e50: 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59   equal SQLITE_SY
6e60: 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65  NC_FULL, that me
6e70: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61  ans.** to use Ma
6e80: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
6e90: 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66  lsync instead of
6ea0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20   fsync()..**.** 
6eb0: 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74  Do not confuse t
6ec0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
6ed0: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
6ee0: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
6ef0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52  .** with the [PR
6f00: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
6f10: 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52  ]=NORMAL and [PR
6f20: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
6f30: 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e  ]=FULL.** settin
6f40: 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72  gs.  The [synchr
6f50: 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65  onous pragma] de
6f60: 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61  termines when ca
6f70: 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  lls to the.** xS
6f80: 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f  ync VFS method o
6f90: 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73  ccur and applies
6fa0: 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73   uniformly acros
6fb0: 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e  s all platforms.
6fc0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53  .** The SQLITE_S
6fd0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
6fe0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
6ff0: 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20  flags determine 
7000: 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63  how.** energetic
7010: 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20   or rigorous or 
7020: 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e  forceful the syn
7030: 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65  c operations are
7040: 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b   and.** only mak
7050: 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f  e a difference o
7060: 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68  n Mac OSX for th
7070: 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65  e default SQLite
7080: 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64   code..** (Third
7090: 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65  -party VFS imple
70a0: 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74  mentations might
70b0: 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64   also make the d
70c0: 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65  istinction.** be
70d0: 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e  tween SQLITE_SYN
70e0: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
70f0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62  ITE_SYNC_FULL, b
7100: 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20  ut among the.** 
7110: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
7120: 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f  s natively suppo
7130: 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20  rted by SQLite, 
7140: 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20  only Mac OSX.** 
7150: 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20  cares about the 
7160: 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a  difference.).*/.
7170: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
7180: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
7190: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
71a0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
71b0: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
71c0: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
71d0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
71e0: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
71f0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
7200: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
7210: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
7220: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
7230: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
7240: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
7250: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
7260: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
7270: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
7280: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
7290: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
72a0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
72b0: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
72c0: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
72d0: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
72e0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
72f0: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
7300: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
7310: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
7320: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
7330: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
7340: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
7350: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
7360: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
7370: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
7380: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
7390: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
73a0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
73b0: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
73c0: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
73d0: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
73e0: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
73f0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
7400: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
7410: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
7420: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
7430: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
7440: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
7450: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
7460: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
7470: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
7480: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
7490: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f  xOpen] method po
74a0: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
74b0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
74c0: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
74d0: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
74e0: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
74f0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7500: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
7510: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
7520: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
7530: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
7540: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
7550: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
7560: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
7570: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
7580: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
7590: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
75a0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
75b0: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
75c0: 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   If the [sqlite3
75d0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
75e0: 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69  od sets the sqli
75f0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
7600: 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f  s element .** to
7610: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
7620: 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71  ter, then the sq
7630: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7640: 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a  .xClose method.*
7650: 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  * may be invoked
7660: 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71   even if the [sq
7670: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7680: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
7690: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
76a0: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
76b0: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
76c0: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
76d0: 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74   a failed [sqlit
76e0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a  e3_vfs.xOpen].**
76f0: 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c   is for the [sql
7700: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7710: 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  to set the sqlit
7720: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
7730: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e   element.** to N
7740: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ULL..**.** The f
7750: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
7760: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
7770: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
7780: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
7790: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
77a0: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
77b0: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
77c0: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20  mal fsync()..** 
77d0: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
77e0: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20  e is a Mac OS X 
77f0: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
7800: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e   The [SQLITE_SYN
7810: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66  C_DATAONLY].** f
7820: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
7830: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  in to indicate t
7840: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74  hat only the dat
7850: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a  a of the file.**
7860: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
7870: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  de needs to be s
7880: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ynced..**.** The
7890: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
78a0: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  to xLock() and x
78b0: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65  Unlock() are one
78c0: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c   of.** <ul>.** <
78d0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
78e0: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _NONE],.** <li> 
78f0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
7900: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RED],.** <li> [S
7910: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
7920: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  VED],.** <li> [S
7930: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
7940: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  NG], or.** <li> 
7950: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
7960: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LUSIVE]..** </ul
7970: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63  >.** xLock() inc
7980: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
7990: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65   xUnlock() decre
79a0: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a  ases the lock..*
79b0: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65  * The xCheckRese
79c0: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f  rvedLock() metho
79d0: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  d checks whether
79e0: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
79f0: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74  nnection,.** eit
7a00: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63  her in this proc
7a10: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f  ess or in some o
7a20: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73  ther process, is
7a30: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52   holding a RESER
7a40: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c  VED,.** PENDING,
7a50: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f   or EXCLUSIVE lo
7a60: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20  ck on the file. 
7a70: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65   It returns true
7a80: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f  .** if such a lo
7a90: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61  ck exists and fa
7aa0: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  lse otherwise..*
7ab0: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f  *.** The xFileCo
7ac0: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
7ad0: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
7ae0: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
7af0: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
7b00: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7b10: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
7b20: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
7b30: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
7b40: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
7b50: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
7b60: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
7b70: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  p" argument is a
7b80: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63  n.** integer opc
7b90: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20  ode.  The third 
7ba0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65  argument is a ge
7bb0: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e  neric pointer in
7bc0: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69  tended to.** poi
7bd0: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72  nt to a structur
7be0: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61  e that may conta
7bf0: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  in arguments or 
7c00: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74  space in which t
7c10: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72  o.** write retur
7c20: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e  n values.  Poten
7c30: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46  tial uses for xF
7c40: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67  ileControl() mig
7c50: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  ht be.** functio
7c60: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f  ns to enable blo
7c70: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68  cking locks with
7c80: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68   timeouts, to ch
7c90: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b  ange the.** lock
7ca0: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f  ing strategy (fo
7cb0: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65  r example to use
7cc0: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29   dot-file locks)
7cd0: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20  , to inquire.** 
7ce0: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73  about the status
7cf0: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74   of a lock, or t
7d00: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f  o break stale lo
7d10: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65  cks.  The SQLite
7d20: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65  .** core reserve
7d30: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65  s all opcodes le
7d40: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
7d50: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20  its own use..** 
7d60: 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A [file control 
7d70: 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f  opcodes | list o
7d80: 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20  f opcodes] less 
7d90: 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69  than 100 is avai
7da0: 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  lable..** Applic
7db0: 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69  ations that defi
7dc0: 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c  ne a custom xFil
7dd0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
7de0: 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64  should use opcod
7df0: 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68  es.** greater th
7e00: 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20  an 100 to avoid 
7e10: 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20  conflicts.  VFS 
7e20: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
7e30: 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
7e40: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
7e50: 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74  D] for file cont
7e60: 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74  rol opcodes that
7e70: 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
7e80: 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a  recognize..**.**
7e90: 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65   The xSectorSize
7ea0: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
7eb0: 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a  s the sector siz
7ec0: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69  e of the.** devi
7ed0: 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65  ce that underlie
7ee0: 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  s the file.  The
7ef0: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20   sector size is 
7f00: 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77  the.** minimum w
7f10: 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65  rite that can be
7f20: 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f   performed witho
7f30: 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a  ut disturbing.**
7f40: 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20   other bytes in 
7f50: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78  the file.  The x
7f60: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
7f70: 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f  stics().** metho
7f80: 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20  d returns a bit 
7f90: 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e  vector describin
7fa0: 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74  g behaviors of t
7fb0: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67  he.** underlying
7fc0: 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c   device:.**.** <
7fd0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
7fe0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7ff0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8000: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
8010: 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  2].** <li> [SQLI
8020: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
8030: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8040: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
8050: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8060: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
8070: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8080: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
8090: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
80a0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
80b0: 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  6K].** <li> [SQL
80c0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
80d0: 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  32K].** <li> [SQ
80e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
80f0: 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C64K].** <li> [S
8100: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
8110: 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e  _APPEND].** <li>
8120: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
8130: 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f  EQUENTIAL].** </
8140: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  ul>.**.** The SQ
8150: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8160: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
8170: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
8180: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
8190: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
81a0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
81b0: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
81c0: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
81d0: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
81e0: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
81f0: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
8200: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
8210: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
8220: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
8230: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
8240: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
8250: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
8260: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
8270: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
8280: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
8290: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
82a0: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
82b0: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
82c0: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
82d0: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
82e0: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
82f0: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
8300: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
8310: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
8320: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
8330: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
8340: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
8350: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
8360: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
8370: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
8380: 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28  .**.** If xRead(
8390: 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  ) returns SQLITE
83a0: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41  _IOERR_SHORT_REA
83b0: 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66  D it must also f
83c0: 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e  ill.** in the un
83d0: 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66  read portions of
83e0: 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68   the buffer with
83f0: 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74   zeros.  A VFS t
8400: 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20  hat.** fails to 
8410: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
8420: 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d  reads might seem
8430: 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76   to work.  Howev
8440: 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74  er,.** failure t
8450: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
8460: 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65  t reads will eve
8470: 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a  ntually lead to.
8480: 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72  ** database corr
8490: 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  uption..*/.typed
84a0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
84b0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c  3_io_methods sql
84c0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b  ite3_io_methods;
84d0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
84e0: 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69  io_methods {.  i
84f0: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69  nt iVersion;.  i
8500: 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c  nt (*xClose)(sql
8510: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
8520: 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69  nt (*xRead)(sqli
8530: 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a  te3_file*, void*
8540: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69  , int iAmt, sqli
8550: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29  te3_int64 iOfst)
8560: 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65  ;.  int (*xWrite
8570: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8580: 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
8590: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
85a0: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
85b0: 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29  int (*xTruncate)
85c0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
85d0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69  sqlite3_int64 si
85e0: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79  ze);.  int (*xSy
85f0: 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  nc)(sqlite3_file
8600: 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20  *, int flags);. 
8610: 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65   int (*xFileSize
8620: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8630: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
8640: 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a  pSize);.  int (*
8650: 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  xLock)(sqlite3_f
8660: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
8670: 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c  t (*xUnlock)(sql
8680: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
8690: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b  ;.  int (*xCheck
86a0: 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71  ReservedLock)(sq
86b0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
86c0: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
86d0: 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  t (*xFileControl
86e0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
86f0: 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70   int op, void *p
8700: 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Arg);.  int (*xS
8710: 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74  ectorSize)(sqlit
8720: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
8730: 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63   (*xDeviceCharac
8740: 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74  teristics)(sqlit
8750: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20  e3_file*);.  /* 
8760: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
8770: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
8780: 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28  ion 1 */.  int (
8790: 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65  *xShmMap)(sqlite
87a0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67  3_file*, int iPg
87b0: 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c  , int pgsz, int,
87c0: 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a   void volatile**
87d0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c  );.  int (*xShmL
87e0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
87f0: 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20  e*, int offset, 
8800: 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73  int n, int flags
8810: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d  );.  void (*xShm
8820: 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33  Barrier)(sqlite3
8830: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
8840: 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69  *xShmUnmap)(sqli
8850: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64  te3_file*, int d
8860: 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a  eleteFlag);.  /*
8870: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
8880: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
8890: 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20  sion 2 */.  int 
88a0: 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74 65  (*xFetch)(sqlite
88b0: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
88c0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e  _int64 iOfst, in
88d0: 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70  t iAmt, void **p
88e0: 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66  p);.  int (*xUnf
88f0: 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69  etch)(sqlite3_fi
8900: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
8910: 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a  64 iOfst, void *
8920: 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  p);.  /* Methods
8930: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
8940: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a   for version 3 *
8950: 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61  /.  /* Additiona
8960: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65  l methods may be
8970: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
8980: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a   releases */.};.
8990: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
89a0: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43   Standard File C
89b0: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a  ontrol Opcodes.*
89c0: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c  * KEYWORDS: {fil
89d0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
89e0: 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  s} {file control
89f0: 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54   opcode}.**.** T
8a00: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
8a10: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64  stants are opcod
8a20: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65  es for the xFile
8a30: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a  Control method.*
8a40: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
8a50: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
8a60: 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65  ject and for the
8a70: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
8a80: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74  ontrol()].** int
8a90: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erface..**.** Th
8aa0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8ab0: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
8ac0: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
8ad0: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
8ae0: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
8af0: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8b00: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
8b10: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
8b20: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
8b30: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
8b40: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
8b50: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
8b60: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
8b70: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
8b80: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
8b90: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
8ba0: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
8bb0: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
8bc0: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
8bd0: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
8be0: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
8bf0: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
8c00: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
8c10: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20   and only needs 
8c20: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20  to be supported 
8c30: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54  when SQLITE_TEST
8c40: 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a  .** is defined..
8c50: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b  ** <ul>.** <li>[
8c60: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
8c70: 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65  ZE_HINT]].** The
8c80: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
8c90: 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65  IZE_HINT] opcode
8ca0: 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69   is used by SQLi
8cb0: 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56  te to give the V
8cc0: 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69  FS.** layer a hi
8cd0: 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20  nt of how large 
8ce0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
8cf0: 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62  e will grow to b
8d00: 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20  e during the.** 
8d10: 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74  current transact
8d20: 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20  ion.  This hint 
8d30: 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  is not guarantee
8d40: 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65  d to be accurate
8d50: 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66   but it.** is of
8d60: 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20  ten close.  The 
8d70: 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d  underlying VFS m
8d80: 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70  ight choose to p
8d90: 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62  reallocate datab
8da0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63  ase.** file spac
8db0: 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20  e based on this 
8dc0: 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f  hint in order to
8dd0: 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20   help writes to 
8de0: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
8df0: 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e  file run faster.
8e00: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
8e10: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
8e20: 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  SIZE]].** The [S
8e30: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
8e40: 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69  K_SIZE] opcode i
8e50: 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73  s used to reques
8e60: 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a  t that the VFS.*
8e70: 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72  * extends and tr
8e80: 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61  uncates the data
8e90: 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75  base file in chu
8ea0: 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70  nks of a size sp
8eb0: 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
8ec0: 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72  e user. The four
8ed0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  th argument to [
8ee0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
8ef0: 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a  trol()] should .
8f00: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69  ** point to an i
8f10: 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74  nteger (type int
8f20: 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  ) containing the
8f30: 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20   new chunk-size 
8f40: 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68  to use.** for th
8f50: 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61  e nominated data
8f60: 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67  base. Allocating
8f70: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73   database file s
8f80: 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a  pace in large.**
8f90: 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42   chunks (say 1MB
8fa0: 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79   at a time), may
8fb0: 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73   reduce file-sys
8fc0: 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f  tem fragmentatio
8fd0: 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65  n and.** improve
8fe0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20   performance on 
8ff0: 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a  some systems..**
9000: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9010: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
9020: 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TER]].** The [SQ
9030: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
9040: 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20  POINTER] opcode 
9050: 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  is used to obtai
9060: 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  n a pointer.** t
9070: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  o the [sqlite3_f
9080: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f  ile] object asso
9090: 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61  ciated with a pa
90a0: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
90b0: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
90c0: 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74    See the [sqlit
90d0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
90e0: 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  )] documentation
90f0: 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
9100: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
9110: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9120: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
9130: 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f  ITTED]].** No lo
9140: 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a  nger in use..**.
9150: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9160: 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20  FCNTL_SYNC]].** 
9170: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9180: 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69  L_SYNC] opcode i
9190: 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65  s generated inte
91a0: 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65  rnally by SQLite
91b0: 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20   and.** sent to 
91c0: 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74  the VFS immediat
91d0: 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20 78  ely before the x
91e0: 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69  Sync method is i
91f0: 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64  nvoked on a.** d
9200: 61 74 61 62 61 73 65 20 66 69 6c 65 20 64 65 73  atabase file des
9210: 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20  criptor. Or, if 
9220: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64  the xSync method
9230: 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
9240: 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65 20  .** because the 
9250: 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75  user has configu
9260: 72 65 64 20 53 51 4c 69 74 65 20 77 69 74 68 20  red SQLite with 
9270: 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  .** [PRAGMA sync
9280: 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41  hronous | PRAGMA
9290: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46   synchronous=OFF
92a0: 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  ] it is invoked 
92b0: 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20  in place .** of 
92c0: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64  the xSync method
92d0: 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c  . In most cases,
92e0: 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67   the pointer arg
92f0: 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69 74  ument passed wit
9300: 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63  h.** this file-c
9310: 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20  ontrol is NULL. 
9320: 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65 20  However, if the 
9330: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73  database file is
9340: 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a   being synced.**
9350: 20 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75   as part of a mu
9360: 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d  lti-database com
9370: 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e  mit, the argumen
9380: 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75  t points to a nu
9390: 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
93a0: 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e  string containin
93b0: 67 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  g the transactio
93c0: 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61  ns master-journa
93d0: 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53  l file name. VFS
93e0: 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e  es that .** do n
93f0: 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67  ot need this sig
9400: 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e  nal should silen
9410: 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20  tly ignore this 
9420: 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74  opcode. Applicat
9430: 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20  ions .** should 
9440: 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65  not call [sqlite
9450: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9460: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f  ] with this opco
9470: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
9480: 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74  ay .** disrupt t
9490: 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  he operation of 
94a0: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
94b0: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65  VFSes that do re
94c0: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
94d0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
94e0: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53  CNTL_COMMIT_PHAS
94f0: 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  ETWO]].** The [S
9500: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
9510: 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63  IT_PHASETWO] opc
9520: 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64  ode is generated
9530: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53   internally by S
9540: 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e  QLite.** and sen
9550: 74 20 74 6f 20 74 68 65 20 56 46 53 20 61 66 74  t to the VFS aft
9560: 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  er a transaction
9570: 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74   has been commit
9580: 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a  ted immediately.
9590: 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74 68  ** but before th
95a0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 75 6e  e database is un
95b0: 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68  locked. VFSes th
95c0: 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  at do not need t
95d0: 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68  his signal.** sh
95e0: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67  ould silently ig
95f0: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65  nore this opcode
9600: 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  . Applications s
9610: 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a  hould not call.*
9620: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
9630: 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20  control()] with 
9640: 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64  this opcode as d
9650: 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72  oing so may disr
9660: 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72  upt the .** oper
9670: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65  ation of the spe
9680: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74  cialized VFSes t
9690: 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69  hat do require i
96a0: 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  t.  .**.** <li>[
96b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
96c0: 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a  N32_AV_RETRY]].*
96d0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
96e0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
96f0: 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  TRY] opcode is u
9700: 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65  sed to configure
9710: 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65   automatic.** re
9720: 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69  try counts and i
9730: 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72  ntervals for cer
9740: 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70  tain disk I/O op
9750: 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  erations for the
9760: 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53  .** windows [VFS
9770: 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72  ] in order to pr
9780: 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73  ovide robustness
9790: 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65   in the presence
97a0: 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75   of.** anti-viru
97b0: 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20  s programs.  By 
97c0: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e  default, the win
97d0: 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65  dows VFS will re
97e0: 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a  try file read,.*
97f0: 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e  * file write, an
9800: 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70  d file delete op
9810: 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31  erations up to 1
9820: 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20  0 times, with a 
9830: 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d  delay.** of 25 m
9840: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f  illiseconds befo
9850: 72 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74  re the first ret
9860: 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20  ry and with the 
9870: 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67  delay increasing
9880: 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69  .** by an additi
9890: 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63  onal 25 millisec
98a0: 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73  onds with each s
98b0: 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e  ubsequent retry.
98c0: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
98d0: 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77   allows these tw
98e0: 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74  o values (10 ret
98f0: 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c  ries and 25 mill
9900: 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61  iseconds of dela
9910: 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75  y).** to be adju
9920: 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65  sted.  The value
9930: 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f  s are changed fo
9940: 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63  r all database c
9950: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69  onnections.** wi
9960: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72  thin the same pr
9970: 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75  ocess.  The argu
9980: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
9990: 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66  r to an array of
99a0: 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73   two.** integers
99b0: 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74   where the first
99c0: 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e   integer i the n
99d0: 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61  ew retry count a
99e0: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  nd the second.**
99f0: 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20   integer is the 
9a00: 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65  delay.  If eithe
9a10: 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67  r integer is neg
9a20: 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
9a30: 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f  setting.** is no
9a40: 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e  t changed but in
9a50: 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20  stead the prior 
9a60: 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65  value of that se
9a70: 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e  tting is written
9a80: 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72  .** into the arr
9a90: 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69  ay entry, allowi
9aa0: 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  ng the current r
9ab0: 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f  etry settings to
9ac0: 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61   be.** interroga
9ad0: 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d  ted.  The zDbNam
9ae0: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  e parameter is i
9af0: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  gnored..**.** <l
9b00: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9b10: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a  _PERSIST_WAL]].*
9b20: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9b30: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
9b40: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9b50: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79   to set or query
9b60: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65   the.** persiste
9b70: 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20  nt [WAL | Write 
9b80: 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69  Ahead Log] setti
9b90: 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ng.  By default,
9ba0: 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a   the auxiliary.*
9bb0: 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f  * write ahead lo
9bc0: 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  g and shared mem
9bd0: 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 20 66  ory files used f
9be0: 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63  or transaction c
9bf0: 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75  ontrol.** are au
9c00: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
9c10: 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74  ted when the lat
9c20: 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  est connection t
9c30: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
9c40: 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69  * closes.  Setti
9c50: 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  ng persistent WA
9c60: 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68  L mode causes th
9c70: 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72  ose files to per
9c80: 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c  sist after.** cl
9c90: 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67  ose.  Persisting
9ca0: 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73   the files is us
9cb0: 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20  eful when other 
9cc0: 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64  processes that d
9cd0: 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72  o not.** have wr
9ce0: 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f  ite permission o
9cf0: 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20  n the directory 
9d00: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64  containing the d
9d10: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e  atabase file wan
9d20: 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65  t.** to read the
9d30: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
9d40: 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73  as the WAL and s
9d50: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
9d60: 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a  es must exist.**
9d70: 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68   in order for th
9d80: 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65  e database to be
9d90: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
9da0: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
9db0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
9dc0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
9dd0: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20  for this opcode 
9de0: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e  should be a poin
9df0: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
9e00: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67  r..** That integ
9e10: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  er is 0 to disab
9e20: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  le persistent WA
9e30: 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65  L mode or 1 to e
9e40: 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  nable persistent
9e50: 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49  .** WAL mode.  I
9e60: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
9e70: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
9e80: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
9e90: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
9ea0: 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20  WAL persistence 
9eb0: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c  setting..**.** <
9ec0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9ed0: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
9ee0: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  WRITE]].** ^The 
9ef0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f  [SQLITE_FCNTL_PO
9f00: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
9f10: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
9f20: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72  d to set or quer
9f30: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74  y the.** persist
9f40: 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f  ent "powersafe-o
9f50: 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53  verwrite" or "PS
9f60: 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68  OW" setting.  Th
9f70: 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a  e PSOW setting.*
9f80: 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65  * determines the
9f90: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50   [SQLITE_IOCAP_P
9fa0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
9fb0: 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a  TE] bit of the.*
9fc0: 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  * xDeviceCharact
9fd0: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73  eristics methods
9fe0: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  . The fourth par
9ff0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
a000: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
a010: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
a020: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
a030: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
a040: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
a050: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
a060: 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61   disable zero-da
a070: 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74  mage mode or 1 t
a080: 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61  o enable zero-da
a090: 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49  mage.** mode.  I
a0a0: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
a0b0: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
a0c0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
a0d0: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
a0e0: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
a0f0: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
a100: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
a110: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  TL_OVERWRITE]].*
a120: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a130: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20  CNTL_OVERWRITE] 
a140: 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65  opcode is invoke
a150: 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65  d by SQLite afte
a160: 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77  r opening.** a w
a170: 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  rite transaction
a180: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
a190: 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20  t, unless it is 
a1a0: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20  rolled back for 
a1b0: 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20  some.** reason, 
a1c0: 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62  the entire datab
a1d0: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  ase file will be
a1e0: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20   overwritten by 
a1f0: 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20  the current .** 
a200: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69  transaction. Thi
a210: 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43  s is used by VAC
a220: 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  UUM operations..
a230: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a240: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
a250: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
a260: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
a270: 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20  ] opcode can be 
a280: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
a290: 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61  he names of.** a
a2a0: 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68  ll [VFSes] in th
a2b0: 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68  e VFS stack.  Th
a2c0: 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61  e names are of a
a2d0: 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64  ll VFS shims and
a2e0: 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f   the.** final bo
a2f0: 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61  ttom-level VFS a
a300: 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  re written into 
a310: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
a320: 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
a330: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
a340: 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74  the result is st
a350: 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72  ored in the char
a360: 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68  * variable.** th
a370: 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  at the fourth pa
a380: 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69  rameter of [sqli
a390: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
a3a0: 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a  ()] points to..*
a3b0: 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20  * The caller is 
a3c0: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
a3d0: 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f  freeing the memo
a3e0: 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41  ry when done.  A
a3f0: 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69  s with.** all fi
a400: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f  le-control actio
a410: 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ns, there is no 
a420: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74  guarantee that t
a430: 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c  his will actuall
a440: 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67  y.** do anything
a450: 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c  .  Callers shoul
a460: 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  d initialize the
a470: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20   char* variable 
a480: 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  to a NULL.** poi
a490: 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69  nter in case thi
a4a0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
a4b0: 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65  s not implemente
a4c0: 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f  d.  This file-co
a4d0: 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65  ntrol.** is inte
a4e0: 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73  nded for diagnos
a4f0: 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a  tic use only..**
a500: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
a510: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a  _FCNTL_PRAGMA]].
a520: 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b  ** ^Whenever a [
a530: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
a540: 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20  t is parsed, an 
a550: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
a560: 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63  AGMA] .** file c
a570: 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74  ontrol is sent t
a580: 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69  o the open [sqli
a590: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
a5a0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
a5b0: 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  * to the databas
a5c0: 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20  e file to which 
a5d0: 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65  the pragma state
a5e0: 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68  ment refers. ^Th
a5f0: 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  e argument.** to
a600: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
a610: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
a620: 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72  control is an ar
a630: 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65  ray of.** pointe
a640: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63  rs to strings (c
a650: 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20  har**) in which 
a660: 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65  the second eleme
a670: 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a  nt of the array.
a680: 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
a690: 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64  f the pragma and
a6a0: 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65   the third eleme
a6b0: 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  nt is the argume
a6c0: 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61  nt to the.** pra
a6d0: 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  gma or NULL if t
a6e0: 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f  he pragma has no
a6f0: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65   argument.  ^The
a700: 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a   handler for an.
a710: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
a720: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
a730: 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e  ntrol can option
a740: 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69  ally make the fi
a750: 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f  rst element.** o
a760: 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67  f the char** arg
a770: 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61  ument point to a
a780: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
a790: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
a7a0: 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20  printf()].** or 
a7b0: 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61  the equivalent a
a7c0: 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77  nd that string w
a7d0: 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72  ill become the r
a7e0: 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61  esult of the pra
a7f0: 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72  gma or.** the er
a800: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74  ror message if t
a810: 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e  he pragma fails.
a820: 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c   ^If the.** [SQL
a830: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a840: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  ] file control r
a850: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e  eturns [SQLITE_N
a860: 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e  OTFOUND], then n
a870: 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d  ormal .** [PRAGM
a880: 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f  A] processing co
a890: 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68  ntinues.  ^If th
a8a0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a8b0: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
a8c0: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20  control returns 
a8d0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65  [SQLITE_OK], the
a8e0: 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73  n the parser ass
a8f0: 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
a900: 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64   VFS has handled
a910: 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65   the PRAGMA itse
a920: 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65  lf and the parse
a930: 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f  r generates a no
a940: 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  -op.** prepared 
a950: 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49 66 20  statement.  ^If 
a960: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
a970: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
a980: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a  ontrol returns.*
a990: 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64  * any result cod
a9a0: 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
a9b0: 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c  LITE_OK] or [SQL
a9c0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74  ITE_NOTFOUND], t
a9d0: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  hat means.** tha
a9e0: 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e  t the VFS encoun
a9f0: 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77  tered an error w
aa00: 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68  hile handling th
aa10: 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74  e [PRAGMA] and t
aa20: 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f  he.** compilatio
aa30: 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20  n of the PRAGMA 
aa40: 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72  fails with an er
aa50: 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  ror.  ^The [SQLI
aa60: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
aa70: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
aa80: 20 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62   occurs at the b
aa90: 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67  eginning of prag
aaa0: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61  ma statement ana
aab0: 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20  lysis and so.** 
aac0: 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76  it is able to ov
aad0: 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20  erride built-in 
aae0: 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65  [PRAGMA] stateme
aaf0: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nts..**.** <li>[
ab00: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55  [SQLITE_FCNTL_BU
ab10: 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e  SYHANDLER]].** ^
ab20: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
ab30: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a  L_BUSYHANDLER].*
ab40: 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d  * file-control m
ab50: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79  ay be invoked by
ab60: 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64   SQLite on the d
ab70: 61 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e  atabase file han
ab80: 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61  dle.** shortly a
ab90: 66 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65  fter it is opene
aba0: 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72  d in order to pr
abb0: 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56  ovide a custom V
abc0: 46 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a  FS with access.*
abd0: 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74  * to the connect
abe0: 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65  ions busy-handle
abf0: 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20  r callback. The 
ac00: 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74  argument is of t
ac10: 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a  ype (void **).**
ac20: 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74   - an array of t
ac30: 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75  wo (void *) valu
ac40: 65 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76  es. The first (v
ac50: 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20  oid *) actually 
ac60: 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66  points.** to a f
ac70: 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20  unction of type 
ac80: 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29  (int (*)(void *)
ac90: 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69  ). In order to i
aca0: 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63  nvoke the connec
acb0: 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61  tions.** busy-ha
acc0: 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63  ndler, this func
acd0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69  tion should be i
ace0: 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20  nvoked with the 
acf0: 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20  second (void *) 
ad00: 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20  in.** the array 
ad10: 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75  as the only argu
ad20: 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75  ment. If it retu
ad30: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
ad40: 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  en the operation
ad50: 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65  .** should be re
ad60: 74 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74  tried. If it ret
ad70: 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63  urns zero, the c
ad80: 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64  ustom VFS should
ad90: 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20   abandon the.** 
ada0: 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f  current operatio
adb0: 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  n..**.** <li>[[S
adc0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
add0: 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41  FILENAME]].** ^A
ade0: 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69  pplication can i
adf0: 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54  nvoke the [SQLIT
ae00: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
ae10: 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72  NAME] file-contr
ae20: 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51  ol.** to have SQ
ae30: 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a  Lite generate a.
ae40: 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
ae50: 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20  ename using the 
ae60: 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74  same algorithm t
ae70: 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20  hat is followed 
ae80: 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74  to generate.** t
ae90: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d  emporary filenam
aea0: 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c  es for TEMP tabl
aeb0: 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74  es and other int
aec0: 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65  ernal uses.  The
aed0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  .** argument sho
aee0: 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20  uld be a char** 
aef0: 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69  which will be fi
af00: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69  lled with the fi
af10: 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65  lename.** writte
af20: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
af30: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
af40: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
af50: 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75   The caller shou
af60: 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71  ld.** invoke [sq
af70: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e  lite3_free()] on
af80: 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61   the result to a
af90: 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65  void a memory le
afa0: 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ak..**.** <li>[[
afb0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
afc0: 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20  P_SIZE]].** The 
afd0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d  [SQLITE_FCNTL_MM
afe0: 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f  AP_SIZE] file co
aff0: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f  ntrol is used to
b000: 20 71 75 65 72 79 20 6f 72 20 73 65 74 20 74 68   query or set th
b010: 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  e.** maximum num
b020: 62 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 61  ber of bytes tha
b030: 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66  t will be used f
b040: 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64  or memory-mapped
b050: 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67   I/O..** The arg
b060: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
b070: 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66  er to a value of
b080: 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e   type sqlite3_in
b090: 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61  t64 that.** is a
b0a0: 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d  n advisory maxim
b0b0: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  um number of byt
b0c0: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74  es in the file t
b0d0: 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54  o memory map.  T
b0e0: 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73  he.** pointer is
b0f0: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
b100: 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e  h the old value.
b110: 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e    The limit is n
b120: 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a  ot changed if.**
b130: 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69   the value origi
b140: 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f  nally pointed to
b150: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e   is negative, an
b160: 64 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74  d so the current
b170: 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62   limit .** can b
b180: 65 20 71 75 65 72 69 65 64 20 62 79 20 70 61 73  e queried by pas
b190: 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65  sing in a pointe
b1a0: 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20  r to a negative 
b1b0: 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a  number.  This.**
b1c0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
b1d0: 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
b1e0: 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50   to implement [P
b1f0: 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
b200: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b210: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  LITE_FCNTL_TRACE
b220: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
b230: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66  E_FCNTL_TRACE] f
b240: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76  ile control prov
b250: 69 64 65 73 20 61 64 76 69 73 6f 72 79 20 69 6e  ides advisory in
b260: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20  formation.** to 
b270: 74 68 65 20 56 46 53 20 61 62 6f 75 74 20 77 68  the VFS about wh
b280: 61 74 20 74 68 65 20 68 69 67 68 65 72 20 6c 61  at the higher la
b290: 79 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c 69  yers of the SQLi
b2a0: 74 65 20 73 74 61 63 6b 20 61 72 65 20 64 6f 69  te stack are doi
b2b0: 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65  ng..** This file
b2c0: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64   control is used
b2d0: 20 62 79 20 73 6f 6d 65 20 56 46 53 20 61 63 74   by some VFS act
b2e0: 69 76 69 74 79 20 74 72 61 63 69 6e 67 20 5b 73  ivity tracing [s
b2f0: 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72  hims]..** The ar
b300: 67 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 72 6f  gument is a zero
b310: 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
b320: 6e 67 2e 20 20 48 69 67 68 65 72 20 6c 61 79 65  ng.  Higher laye
b330: 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c  rs in the.** SQL
b340: 69 74 65 20 73 74 61 63 6b 20 6d 61 79 20 67 65  ite stack may ge
b350: 6e 65 72 61 74 65 20 69 6e 73 74 61 6e 63 65 73  nerate instances
b360: 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20 63 6f   of this file co
b370: 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20  ntrol if.** the 
b380: 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54  [SQLITE_USE_FCNT
b390: 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65  L_TRACE] compile
b3a0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
b3b0: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  enabled..**.** <
b3c0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b3d0: 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a  L_HAS_MOVED]].**
b3e0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
b3f0: 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69  TL_HAS_MOVED] fi
b400: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72  le control inter
b410: 70 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65  prets its argume
b420: 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  nt as a.** point
b430: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
b440: 20 61 6e 64 20 69 74 20 77 72 69 74 65 73 20 61   and it writes a
b450: 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68   boolean into th
b460: 61 74 20 69 6e 74 65 67 65 72 20 64 65 70 65 6e  at integer depen
b470: 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68  ding.** on wheth
b480: 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 69  er or not the fi
b490: 6c 65 20 68 61 73 20 62 65 65 6e 20 72 65 6e 61  le has been rena
b4a0: 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64  med, moved, or d
b4b0: 65 6c 65 74 65 64 20 73 69 6e 63 65 20 69 74 0a  eleted since it.
b4c0: 2a 2a 20 77 61 73 20 66 69 72 73 74 20 6f 70 65  ** was first ope
b4d0: 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ned..**.** <li>[
b4e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
b4f0: 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d  N32_SET_HANDLE]]
b500: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
b510: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f  FCNTL_WIN32_SET_
b520: 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69  HANDLE] opcode i
b530: 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67  s used for debug
b540: 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f  ging.  This.** o
b550: 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65  pcode causes the
b560: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
b570: 74 68 6f 64 20 74 6f 20 73 77 61 70 20 74 68 65  thod to swap the
b580: 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 69 74   file handle wit
b590: 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69  h the one.** poi
b5a0: 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 70  nted to by the p
b5b0: 41 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 20 54  Arg argument.  T
b5c0: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 20 69  his capability i
b5d0: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
b5e0: 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c  sting.** and onl
b5f0: 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75  y needs to be su
b600: 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c  pported when SQL
b610: 49 54 45 5f 54 45 53 54 20 69 73 20 64 65 66 69  ITE_TEST is defi
b620: 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e  ned..**.** </ul>
b630: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
b640: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
b650: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
b660: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
b670: 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_GET_LOCKPROXYF
b680: 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ILE             
b690: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
b6a0: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
b6b0: 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20 33  LE             3
b6c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b6d0: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20  LAST_ERRNO      
b6e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a                4.
b6f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b700: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20  CNTL_SIZE_HINT  
b710: 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
b720: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b730: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20  NTL_CHUNK_SIZE  
b740: 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
b750: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b760: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20  TL_FILE_POINTER 
b770: 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
b780: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b790: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20  L_SYNC_OMITTED  
b7a0: 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66            8.#def
b7b0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b7c0: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20  _WIN32_AV_RETRY 
b7d0: 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69           9.#defi
b7e0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b7f0: 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20  PERSIST_WAL     
b800: 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e         10.#defin
b810: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f  e SQLITE_FCNTL_O
b820: 56 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20  VERWRITE        
b830: 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65        11.#define
b840: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46   SQLITE_FCNTL_VF
b850: 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20  SNAME           
b860: 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20       12.#define 
b870: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
b880: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
b890: 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53      13.#define S
b8a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
b8b0: 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
b8c0: 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51     14.#define SQ
b8d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48  LITE_FCNTL_BUSYH
b8e0: 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20  ANDLER          
b8f0: 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c    15.#define SQL
b900: 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49  ITE_FCNTL_TEMPFI
b910: 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  LENAME          
b920: 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   16.#define SQLI
b930: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
b940: 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
b950: 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  18.#define SQLIT
b960: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20  E_FCNTL_TRACE   
b970: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
b980: 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
b990: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44  _FCNTL_HAS_MOVED
b9a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
b9b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b9c0: 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20 20  FCNTL_SYNC      
b9d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 0a               21.
b9e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b9f0: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53  CNTL_COMMIT_PHAS
ba00: 45 54 57 4f 20 20 20 20 20 20 20 20 32 32 0a 23  ETWO        22.#
ba10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
ba20: 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41  NTL_WIN32_SET_HA
ba30: 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a 0a 2f  NDLE       23../
ba40: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
ba50: 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  utex Handle.**.*
ba60: 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75  * The mutex modu
ba70: 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65  le within SQLite
ba80: 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65   defines [sqlite
ba90: 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61  3_mutex] to be a
baa0: 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79  n.** abstract ty
bab0: 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f  pe for a mutex o
bac0: 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69  bject.  The SQLi
bad0: 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f  te core never lo
bae0: 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e  oks.** at the in
baf0: 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
bb00: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c  ation of an [sql
bb10: 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74  ite3_mutex].  It
bb20: 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77   only.** deals w
bb30: 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  ith pointers to 
bb40: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
bb50: 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  ex] object..**.*
bb60: 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72  * Mutexes are cr
bb70: 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  eated using [sql
bb80: 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
bb90: 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
bba0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
bbb0: 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74  utex sqlite3_mut
bbc0: 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ex;../*.** CAPI3
bbd0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
bbe0: 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41  e Object.**.** A
bbf0: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
bc00: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
bc10: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
bc20: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
bc30: 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65  en.** the SQLite
bc40: 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e   core and the un
bc50: 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69  derlying operati
bc60: 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20  ng system.  The 
bc70: 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20  "vfs".** in the 
bc80: 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65  name of the obje
bc90: 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76  ct stands for "v
bca0: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
bcb0: 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65  em".  See.** the
bcc0: 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75   [VFS | VFS docu
bcd0: 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66  mentation] for f
bce0: 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69  urther informati
bcf0: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61  on..**.** The va
bd00: 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73  lue of the iVers
bd10: 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69  ion field is ini
bd20: 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79  tially 1 but may
bd30: 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a   be larger in.**
bd40: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
bd50: 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64   of SQLite.  Add
bd60: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d  itional fields m
bd70: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74  ay be appended t
bd80: 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74  o this.** object
bd90: 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69   when the iVersi
bda0: 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72  on value is incr
bdb0: 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61  eased.  Note tha
bdc0: 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a  t the structure.
bdd0: 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
bde0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61  3_vfs object cha
bdf0: 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e  nges in the tran
be00: 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a  saction between.
be10: 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
be20: 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e  n 3.5.9 and 3.6.
be30: 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56  0 and yet the iV
be40: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73  ersion field was
be50: 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   not.** modified
be60: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73  ..**.** The szOs
be70: 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68  File field is th
be80: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75  e size of the su
be90: 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65  bclassed [sqlite
bea0: 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63  3_file].** struc
beb0: 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69  ture used by thi
bec0: 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61  s VFS.  mxPathna
bed0: 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  me is the maximu
bee0: 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61  m length of.** a
bef0: 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69   pathname in thi
bf00: 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67  s VFS..**.** Reg
bf10: 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f  istered sqlite3_
bf20: 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20  vfs objects are 
bf30: 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64  kept on a linked
bf40: 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a   list formed by.
bf50: 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  ** the pNext poi
bf60: 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69  nter.  The [sqli
bf70: 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
bf80: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
bf90: 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
bfa0: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  er()] interfaces
bfb0: 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73   manage this lis
bfc0: 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64  t.** in a thread
bfd0: 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20  -safe way.  The 
bfe0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e  [sqlite3_vfs_fin
bff0: 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  d()] interface.*
c000: 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c  * searches the l
c010: 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68  ist.  Neither th
c020: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  e application co
c030: 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a  de nor the VFS.*
c040: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
c050: 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20   should use the 
c060: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a  pNext pointer..*
c070: 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66  *.** The pNext f
c080: 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79  ield is the only
c090: 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71   field in the sq
c0a0: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72  lite3_vfs.** str
c0b0: 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69  ucture that SQLi
c0c0: 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64  te will ever mod
c0d0: 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ify.  SQLite wil
c0e0: 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a  l only access.**
c0f0: 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
c100: 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64  field while hold
c110: 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72  ing a particular
c120: 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a   static mutex..*
c130: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
c140: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d  n should never m
c150: 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77  odify anything w
c160: 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ithin the sqlite
c170: 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20  3_vfs.** object 
c180: 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20  once the object 
c190: 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65  has been registe
c1a0: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a  red..**.** The z
c1b0: 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73  Name field holds
c1c0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
c1d0: 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68   VFS module.  Th
c1e0: 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62  e name must.** b
c1f0: 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20  e unique across 
c200: 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e  all VFS modules.
c210: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
c220: 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20  _vfs.xOpen]].** 
c230: 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
c240: 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c  es that the zFil
c250: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
c260: 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65  to xOpen.** is e
c270: 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
c280: 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f  nter or string o
c290: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
c2a0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20  xFullPathname() 
c2b0: 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c  with an optional
c2c0: 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a   suffix added..*
c2d0: 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69  * ^If a suffix i
c2e0: 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a  s added to the z
c2f0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
c300: 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63  er, it will.** c
c310: 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67  onsist of a sing
c320: 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72  le "-" character
c330: 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20   followed by no 
c340: 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20  more than.** 11 
c350: 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64  alphanumeric and
c360: 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65  /or "-" characte
c370: 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66  rs..** ^SQLite f
c380: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
c390: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
c3a0: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
c3b0: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
c3c0: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
c3d0: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
c3e0: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
c3f0: 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a  vious sentence,.
c400: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
c410: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
c420: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
c430: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
c440: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
c450: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
c460: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
c470: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
c480: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
c490: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
c4a0: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
c4b0: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
c4c0: 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73   must invent its
c4d0: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
c4e0: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
c4f0: 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65  .  ^Whenever the
c500: 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70   .** xFilename p
c510: 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c  arameter is NULL
c520: 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65   it will also be
c530: 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
c540: 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61  he.** flags para
c550: 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75  meter will inclu
c560: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
c570: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a  DELETEONCLOSE]..
c580: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
c590: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
c5a0: 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  n() includes all
c5b0: 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20   bits set in.** 
c5c0: 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
c5d0: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  nt to [sqlite3_o
c5e0: 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69  pen_v2()].  Or i
c5f0: 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  f [sqlite3_open(
c600: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
c610: 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75  3_open16()] is u
c620: 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20  sed, then flags 
c630: 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73  includes at leas
c640: 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  t.** [SQLITE_OPE
c650: 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
c660: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
c670: 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65  TE]. .** If xOpe
c680: 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65  n() opens a file
c690: 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20   read-only then 
c6a0: 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61  it sets *pOutFla
c6b0: 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65  gs to.** include
c6c0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
c6d0: 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20  ADONLY].  Other 
c6e0: 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61  bits in *pOutFla
c6f0: 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a  gs may be set..*
c700: 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69  *.** ^(SQLite wi
c710: 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ll also add one 
c720: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
c730: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
c740: 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64  pen().** call, d
c750: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
c760: 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65  object being ope
c770: 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ned:.**.** <ul>.
c780: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
c790: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a  _OPEN_MAIN_DB].*
c7a0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
c7b0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
c7c0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
c7d0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
c7e0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
c7f0: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
c800: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
c810: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
c820: 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  SIENT_DB].** <li
c830: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
c840: 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  SUBJOURNAL].** <
c850: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
c860: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
c870: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
c880: 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20  TE_OPEN_WAL].** 
c890: 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
c8a0: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
c8b0: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
c8c0: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
c8d0: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
c8e0: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
c8f0: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
c900: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
c910: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
c920: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
c930: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
c940: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
c950: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
c960: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
c970: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
c980: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
c990: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
c9a0: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
c9b0: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
c9c0: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
c9d0: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
c9e0: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
c9f0: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
ca00: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
ca10: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
ca20: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
ca30: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
ca40: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
ca50: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
ca60: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
ca70: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
ca80: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
ca90: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
caa0: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
cab0: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
cac0: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
cad0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
cae0: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
caf0: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
cb00: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
cb10: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
cb20: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
cb30: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
cb40: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
cb50: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
cb60: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
cb70: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
cb80: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
cb90: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
cba0: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
cbb0: 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
cbc0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
cbd0: 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73  SE].** will be s
cbe0: 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61  et for TEMP data
cbf0: 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20  bases and their 
cc00: 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69  journals, transi
cc10: 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73  ent.** databases
cc20: 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c  , and subjournal
cc30: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  s..**.** ^The [S
cc40: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
cc50: 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c  SIVE] flag is al
cc60: 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e  ways used in con
cc70: 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68  junction.** with
cc80: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
cc90: 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20  N_CREATE] flag, 
cca0: 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64  which are both d
ccb0: 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f  irectly.** analo
ccc0: 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58  gous to the O_EX
ccd0: 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66  CL and O_CREAT f
cce0: 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49  lags of the POSI
ccf0: 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e  X open().** API.
cd00: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45    The SQLITE_OPE
cd10: 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  N_EXCLUSIVE flag
cd20: 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69  , when paired wi
cd30: 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54  th the .** SQLIT
cd40: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69  E_OPEN_CREATE, i
cd50: 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  s used to indica
cd60: 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f  te that file sho
cd70: 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  uld always.** be
cd80: 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68   created, and th
cd90: 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f  at it is an erro
cda0: 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20  r if it already 
cdb0: 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73  exists..** It is
cdc0: 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64   <i>not</i> used
cdd0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65   to indicate the
cde0: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20   file should be 
cdf0: 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65  opened .** for e
ce00: 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e  xclusive access.
ce10: 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74  .**.** ^At least
ce20: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
ce30: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
ce40: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
ce50: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
ce60: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
ce70: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
ce80: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
ce90: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
cea0: 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  pen.  The xOpen 
ceb0: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
cec0: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
ced0: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
cee0: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
cef0: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e  t fill it in.  N
cf00: 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ote that.** the 
cf10: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73  xOpen method mus
cf20: 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  t set the sqlite
cf30: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
cf40: 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76  to either.** a v
cf50: 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f  alid [sqlite3_io
cf60: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
cf70: 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f   or to NULL.  xO
cf80: 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74  pen must do.** t
cf90: 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20  his even if the 
cfa0: 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c  open fails.  SQL
cfb0: 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74  ite expects that
cfc0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
cfd0: 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c  e.pMethods.** el
cfe0: 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61  ement will be va
cff0: 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20  lid after xOpen 
d000: 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65  returns regardle
d010: 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
d020: 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20  s.** or failure 
d030: 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c  of the xOpen cal
d040: 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  l..**.** [[sqlit
d050: 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d  e3_vfs.xAccess]]
d060: 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61  .** ^The flags a
d070: 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65  rgument to xAcce
d080: 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c  ss() may be [SQL
d090: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
d0a0: 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f  S].** to test fo
d0b0: 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20  r the existence 
d0c0: 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53  of a file, or [S
d0d0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
d0e0: 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65  DWRITE] to.** te
d0f0: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
d100: 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e  e is readable an
d110: 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b  d writable, or [
d120: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
d130: 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77  AD].** to test w
d140: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
d150: 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62   at least readab
d160: 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63  le.   The file c
d170: 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63  an be a.** direc
d180: 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  tory..**.** ^SQL
d190: 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ite will always 
d1a0: 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73  allocate at leas
d1b0: 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62  t mxPathname+1 b
d1c0: 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ytes for the.** 
d1d0: 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78 46  output buffer xF
d1e0: 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68  ullPathname.  Th
d1f0: 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20  e exact size of 
d200: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
d210: 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73  r.** is also pas
d220: 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74  sed as a paramet
d230: 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68  er to both  meth
d240: 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70  ods. If the outp
d250: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
d260: 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68  not large enough
d270: 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  , [SQLITE_CANTOP
d280: 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65  EN] should be re
d290: 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68  turned. Since th
d2a0: 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64  is is.** handled
d2b0: 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f   as a fatal erro
d2c0: 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73  r by SQLite, vfs
d2d0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
d2e0: 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72   should endeavor
d2f0: 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74  .** to prevent t
d300: 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d  his by setting m
d310: 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73  xPathname to a s
d320: 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67  ufficiently larg
d330: 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  e value..**.** T
d340: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
d350: 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72  , xSleep(), xCur
d360: 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20  rentTime(), and 
d370: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
d380: 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  4().** interface
d390: 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74  s are not strict
d3a0: 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65  ly a part of the
d3b0: 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74   filesystem, but
d3c0: 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63   they are.** inc
d3d0: 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53  luded in the VFS
d3e0: 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63   structure for c
d3f0: 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20  ompleteness..** 
d400: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
d410: 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d  ) function attem
d420: 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42  pts to return nB
d430: 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ytes bytes.** of
d440: 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61   good-quality ra
d450: 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f  ndomness into zO
d460: 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20  ut.  The return 
d470: 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20  value is.** the 
d480: 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66  actual number of
d490: 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
d4a0: 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a  ness obtained..*
d4b0: 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d  * The xSleep() m
d4c0: 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65  ethod causes the
d4d0: 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20   calling thread 
d4e0: 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a  to sleep for at.
d4f0: 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d  ** least the num
d500: 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f  ber of microseco
d510: 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65  nds given.  ^The
d520: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a   xCurrentTime().
d530: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
d540: 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e  s a Julian Day N
d550: 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75  umber for the cu
d560: 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74  rrent date and t
d570: 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61  ime as.** a floa
d580: 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
d590: 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65  ..** ^The xCurre
d5a0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
d5b0: 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73  thod returns, as
d5c0: 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65   an integer, the
d5d0: 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e   Julian.** Day N
d5e0: 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64  umber multiplied
d5f0: 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74 68   by 86400000 (th
d600: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
d610: 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20  iseconds in .** 
d620: 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20  a 24-hour day). 
d630: 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c   .** ^SQLite wil
d640: 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72 65  l use the xCurre
d650: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
d660: 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20  thod to get the 
d670: 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20  current.** date 
d680: 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61 74  and time if that
d690: 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c   method is avail
d6a0: 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f  able (if iVersio
d6b0: 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72  n is 2 or .** gr
d6c0: 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66 75  eater and the fu
d6d0: 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
d6e0: 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20  s not NULL) and 
d6f0: 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a  will fall back.*
d700: 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d  * to xCurrentTim
d710: 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74 54  e() if xCurrentT
d720: 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e  imeInt64() is un
d730: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  available..**.**
d740: 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65 6d   ^The xSetSystem
d750: 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74  Call(), xGetSyst
d760: 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e  emCall(), and xN
d770: 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20  estSystemCall() 
d780: 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72  interfaces.** ar
d790: 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68  e not used by th
d7a0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20  e SQLite core.  
d7b0: 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69  These optional i
d7c0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72  nterfaces are pr
d7d0: 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d  ovided.** by som
d7e0: 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c  e VFSes to facil
d7f0: 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66  itate testing of
d800: 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42   the VFS code. B
d810: 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a  y overriding .**
d820: 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69   system calls wi
d830: 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64  th functions und
d840: 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20  er its control, 
d850: 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63  a test program c
d860: 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66  an.** simulate f
d870: 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20  aults and error 
d880: 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20  conditions that 
d890: 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20  would otherwise 
d8a0: 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20  be difficult.** 
d8b0: 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f  or impossible to
d8c0: 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65   induce.  The se
d8d0: 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c  t of system call
d8e0: 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76  s that can be ov
d8f0: 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69  erridden.** vari
d900: 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20  es from one VFS 
d910: 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20  to another, and 
d920: 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e  from one version
d930: 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46 53   of the same VFS
d940: 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e   to the.** next.
d950: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
d960: 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69 6e  hat use these in
d970: 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62 65  terfaces must be
d980: 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e   prepared for an
d990: 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74  y.** or all of t
d9a0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
d9b0: 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f  to be NULL or fo
d9c0: 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f 72  r their behavior
d9d0: 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72   to change.** fr
d9e0: 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74  om one release t
d9f0: 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70  o the next.  App
da00: 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e  lications must n
da10: 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63  ot attempt to ac
da20: 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74  cess.** any of t
da30: 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20  hese methods if 
da40: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20  the iVersion of 
da50: 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73 20  the VFS is less 
da60: 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64  than 3..*/.typed
da70: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
da80: 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66  3_vfs sqlite3_vf
da90: 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  s;.typedef void 
daa0: 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  (*sqlite3_syscal
dab0: 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74  l_ptr)(void);.st
dac0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
dad0: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
dae0: 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  n;            /*
daf0: 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69   Structure versi
db00: 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65  on number (curre
db10: 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74  ntly 3) */.  int
db20: 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20   szOsFile;      
db30: 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66        /* Size of
db40: 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69   subclassed sqli
db50: 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e  te3_file */.  in
db60: 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20  t mxPathname;   
db70: 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
db80: 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  m file pathname 
db90: 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69  length */.  sqli
dba0: 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20  te3_vfs *pNext; 
dbb0: 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67       /* Next reg
dbc0: 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20  istered VFS */. 
dbd0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
dbe0: 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  me;       /* Nam
dbf0: 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61  e of this virtua
dc00: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f  l file system */
dc10: 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
dc20: 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50  a;          /* P
dc30: 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63  ointer to applic
dc40: 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64  ation-specific d
dc50: 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ata */.  int (*x
dc60: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
dc70: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
dc80: 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66  zName, sqlite3_f
dc90: 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20  ile*,.          
dca0: 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20       int flags, 
dcb0: 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b  int *pOutFlags);
dcc0: 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65  .  int (*xDelete
dcd0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
dce0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
dcf0: 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b  e, int syncDir);
dd00: 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73  .  int (*xAccess
dd10: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
dd20: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
dd30: 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e  e, int flags, in
dd40: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
dd50: 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61  nt (*xFullPathna
dd60: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
dd70: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
dd80: 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63  ame, int nOut, c
dd90: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f  har *zOut);.  vo
dda0: 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73  id *(*xDlOpen)(s
ddb0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
ddc0: 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
ddd0: 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  me);.  void (*xD
dde0: 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  lError)(sqlite3_
ddf0: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
de00: 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b   char *zErrMsg);
de10: 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53  .  void (*(*xDlS
de20: 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ym)(sqlite3_vfs*
de30: 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68  ,void*, const ch
de40: 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f  ar *zSymbol))(vo
de50: 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  id);.  void (*xD
de60: 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  lClose)(sqlite3_
de70: 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20  vfs*, void*);.  
de80: 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73  int (*xRandomnes
de90: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
dea0: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
deb0: 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28   *zOut);.  int (
dec0: 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33  *xSleep)(sqlite3
ded0: 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f  _vfs*, int micro
dee0: 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20  seconds);.  int 
def0: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28  (*xCurrentTime)(
df00: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f  sqlite3_vfs*, do
df10: 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  uble*);.  int (*
df20: 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73  xGetLastError)(s
df30: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
df40: 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a  , char *);.  /*.
df50: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
df60: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
df70: 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73  rsion 1 of the s
df80: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
df90: 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e  .  ** definition
dfa0: 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f  .  Those that fo
dfb0: 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 69  llow are added i
dfc0: 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c  n version 2 or l
dfd0: 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ater.  */.  int 
dfe0: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  (*xCurrentTimeIn
dff0: 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73  t64)(sqlite3_vfs
e000: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
e010: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
e020: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
e030: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
e040: 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73  1 and 2 of the s
e050: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
e060: 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c  ..  ** Those bel
e070: 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73 69  ow are for versi
e080: 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65 72  on 3 and greater
e090: 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ..  */.  int (*x
e0a0: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  SetSystemCall)(s
e0b0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
e0c0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
e0d0: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
e0e0: 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f  ptr);.  sqlite3_
e0f0: 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47  syscall_ptr (*xG
e100: 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  etSystemCall)(sq
e110: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
e120: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
e130: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a    const char *(*
e140: 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29  xNextSystemCall)
e150: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
e160: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
e170: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
e180: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
e190: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31  re in versions 1
e1a0: 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68   through 3 of th
e1b0: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
e1c0: 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69  ect..  ** New fi
e1d0: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
e1e0: 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76  nded in figure v
e1f0: 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56  ersions.  The iV
e200: 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75  ersion.  ** valu
e210: 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74  e will increment
e220: 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68   whenever this h
e230: 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b  appens. .  */.};
e240: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
e250: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
e260: 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68  xAccess VFS meth
e270: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
e280: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
e290: 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
e2a0: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
e2b0: 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41  ter to.** the xA
e2c0: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  ccess method of 
e2d0: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  an [sqlite3_vfs]
e2e0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64   object.  They d
e2f0: 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74  etermine.** what
e300: 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73   kind of permiss
e310: 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73  ions the xAccess
e320: 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69   method is looki
e330: 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20  ng for..** With 
e340: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
e350: 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73  ISTS, the xAcces
e360: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70  s method.** simp
e370: 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ly checks whethe
e380: 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74  r the file exist
e390: 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  s..** With SQLIT
e3a0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
e3b0: 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TE, the xAccess 
e3c0: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
e3d0: 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d   whether the nam
e3e0: 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20  ed directory is 
e3f0: 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e  both readable an
e400: 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69  d writable.** (i
e410: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
e420: 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61  f files can be a
e430: 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61  dded, removed, a
e440: 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69  nd renamed withi
e450: 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f  n.** the directo
e460: 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ry)..** The SQLI
e470: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
e480: 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20  ITE constant is 
e490: 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f  currently used o
e4a0: 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74  nly by the.** [t
e4b0: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
e4c0: 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f  ory pragma], tho
e4d0: 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63  ugh this could c
e4e0: 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72  hange in a futur
e4f0: 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20  e.** release of 
e500: 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20  SQLite..** With 
e510: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
e520: 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  AD, the xAccess 
e530: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
e540: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
e550: 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20  e is readable.  
e560: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
e570: 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20  S_READ constant 
e580: 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  is.** currently 
e590: 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69  unused, though i
e5a0: 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20  t might be used 
e5b0: 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65  in a future rele
e5c0: 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
e5d0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
e5e0: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
e5f0: 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53  S    0.#define S
e600: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
e610: 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73  DWRITE 1   /* Us
e620: 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d  ed by PRAGMA tem
e630: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
e640: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
e650: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
e660: 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73       2   /* Unus
e670: 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
e680: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
e690: 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46   the xShmLock VF
e6a0: 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54  S method.**.** T
e6b0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
e6c0: 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68  stants define th
e6d0: 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e  e various lockin
e6e0: 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  g operations.** 
e6f0: 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78  allowed by the x
e700: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
e710: 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  f [sqlite3_io_me
e720: 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20  thods].  The.** 
e730: 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68  following are th
e740: 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d  e only legal com
e750: 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61  binations of fla
e760: 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68  gs to the.** xSh
e770: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a  mLock method:.**
e780: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
e790: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
e7a0: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
e7b0: 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
e7c0: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c  QLITE_SHM_LOCK |
e7d0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
e7e0: 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53  USIVE.** <li>  S
e7f0: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
e800: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48   | SQLITE_SHM_SH
e810: 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  ARED.** <li>  SQ
e820: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
e830: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
e840: 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a  LUSIVE.** </ul>.
e850: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63  **.** When unloc
e860: 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53  king, the same S
e870: 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49  HARED or EXCLUSI
e880: 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20  VE flag must be 
e890: 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77  supplied as.** w
e8a0: 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20  as given no the 
e8b0: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f  corresponding lo
e8c0: 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ck.  .**.** The 
e8d0: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
e8e0: 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  can transition b
e8f0: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
e900: 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a  and SHARED or.**
e910: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
e920: 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  d and EXCLUSIVE.
e930: 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e    It cannot tran
e940: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53  sition between S
e950: 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43  HARED.** and EXC
e960: 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69  LUSIVE..*/.#defi
e970: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  ne SQLITE_SHM_UN
e980: 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65  LOCK       1.#de
e990: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
e9a0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23  LOCK         2.#
e9b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
e9c0: 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34  M_SHARED       4
e9d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e9e0: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20  SHM_EXCLUSIVE   
e9f0: 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   8../*.** CAPI3R
ea00: 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d  EF: Maximum xShm
ea10: 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a  Lock index.**.**
ea20: 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   The xShmLock me
ea30: 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33  thod on [sqlite3
ea40: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79  _io_methods] may
ea50: 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62   use values.** b
ea60: 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69  etween 0 and thi
ea70: 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73  s upper bound as
ea80: 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72   its "offset" ar
ea90: 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53  gument..** The S
eaa0: 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20  QLite core will 
eab0: 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f  never attempt to
eac0: 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65   acquire or rele
ead0: 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75  ase a.** lock ou
eae0: 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61  tside of this ra
eaf0: 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge.*/.#define S
eb00: 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20  QLITE_SHM_NLOCK 
eb10: 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a         8.../*.**
eb20: 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69   CAPI3REF: Initi
eb30: 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65  alize The SQLite
eb40: 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e   Library.**.** ^
eb50: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
eb60: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
eb70: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
eb80: 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61  .** SQLite libra
eb90: 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ry.  ^The sqlite
eba0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75  3_shutdown() rou
ebb0: 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61  tine.** dealloca
ebc0: 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65  tes any resource
ebd0: 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f  s that were allo
ebe0: 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
ebf0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a  _initialize()..*
ec00: 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
ec10: 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f   are designed to
ec20: 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20   aid in process 
ec30: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
ec40: 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f  nd.** shutdown o
ec50: 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65  n embedded syste
ec60: 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e  ms.  Workstation
ec70: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73   applications us
ec80: 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f  ing.** SQLite no
ec90: 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65  rmally do not ne
eca0: 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74  ed to invoke eit
ecb0: 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75  her of these rou
ecc0: 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63  tines..**.** A c
ecd0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
ece0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61  nitialize() is a
ecf0: 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
ed00: 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74  ll if it is.** t
ed10: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
ed20: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ed30: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75  () is invoked du
ed40: 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d  ring the lifetim
ed50: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63  e of.** the proc
ed60: 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73  ess, or if it is
ed70: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
ed80: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ed90: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
eda0: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ** following a c
edb0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
edc0: 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e  hutdown().  ^(On
edd0: 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ly an effective 
ede0: 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  call.** of sqlit
edf0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
ee00: 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c  does any initial
ee10: 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74  ization.  All ot
ee20: 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65  her calls.** are
ee30: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
ee40: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  .)^.**.** A call
ee50: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
ee60: 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66  down() is an "ef
ee70: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
ee80: 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
ee90: 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  .** call to sqli
eea0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73  te3_shutdown() s
eeb0: 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71  ince the last sq
eec0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
eed0: 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61  ().  ^(Only.** a
eee0: 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
eef0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
ef00: 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20  down() does any 
ef10: 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  deinitialization
ef20: 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76  ..** All other v
ef30: 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71  alid calls to sq
ef40: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
ef50: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
ef60: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  -ops.)^.**.** Th
ef70: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
ef80: 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65  lize() interface
ef90: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20   is threadsafe, 
efa0: 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  but sqlite3_shut
efb0: 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74  down().** is not
efc0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  .  The sqlite3_s
efd0: 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66  hutdown() interf
efe0: 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65  ace must only be
eff0: 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a   called from a.*
f000: 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  * single thread.
f010: 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61    All open [data
f020: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
f030: 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64  ] must be closed
f040: 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65   and all.** othe
f050: 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63  r SQLite resourc
f060: 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c  es must be deall
f070: 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20  ocated prior to 
f080: 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69  invoking.** sqli
f090: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a  te3_shutdown()..
f0a0: 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65  **.** Among othe
f0b0: 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74  r things, ^sqlit
f0c0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f0d0: 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  will invoke.** s
f0e0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
f0f0: 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73  .  Similarly, ^s
f100: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f110: 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  ).** will invoke
f120: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
f130: 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )..**.** ^The sq
f140: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f150: 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
f160: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  ns [SQLITE_OK] o
f170: 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49  n success..** ^I
f180: 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  f for some reaso
f190: 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  n, sqlite3_initi
f1a0: 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c  alize() is unabl
f1b0: 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a  e to initialize.
f1c0: 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28  ** the library (
f1d0: 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e  perhaps it is un
f1e0: 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
f1f0: 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72   a needed resour
f200: 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20  ce such.** as a 
f210: 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e  mutex) it return
f220: 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  s an [error code
f230: 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  ] other than [SQ
f240: 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
f250: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
f260: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
f270: 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65  e is called inte
f280: 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f  rnally by many o
f290: 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
f2a0: 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61  nterfaces so tha
f2b0: 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  t an application
f2c0: 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f   usually does no
f2d0: 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76  t need to.** inv
f2e0: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
f2f0: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
f300: 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  y.  For example,
f310: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
f320: 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74  ].** calls sqlit
f330: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f340: 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  so the SQLite li
f350: 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75  brary will be au
f360: 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69  tomatically.** i
f370: 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20  nitialized when 
f380: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
f390: 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74   is called if it
f3a0: 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74   has not be init
f3b0: 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61  ialized.** alrea
f3c0: 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69  dy.  ^However, i
f3d0: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
f3e0: 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53  iled with the [S
f3f0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
f400: 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  NIT].** compile-
f410: 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65  time option, the
f420: 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20  n the automatic 
f430: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
f440: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
f450: 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64   are omitted and
f460: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
f470: 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74   must call sqlit
f480: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f490: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f  directly.** prio
f4a0: 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
f4b0: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
f4c0: 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69  rface.  For maxi
f4d0: 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c  mum portability,
f4e0: 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  .** it is recomm
f4f0: 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
f500: 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69  cations always i
f510: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
f520: 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69  itialize().** di
f530: 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20  rectly prior to 
f540: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
f550: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
f560: 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73  .  Future releas
f570: 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20  es.** of SQLite 
f580: 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73  may require this
f590: 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
f5a0: 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  s, the behavior 
f5b0: 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65  exhibited.** whe
f5c0: 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
f5d0: 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
f5e0: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
f5f0: 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68   might become th
f600: 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68  e.** default beh
f610: 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75  avior in some fu
f620: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20  ture release of 
f630: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
f640: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
f650: 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  t() routine does
f660: 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
f670: 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e  m specific.** in
f680: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
f690: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
f6a0: 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ry.  The sqlite3
f6b0: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75  _os_end().** rou
f6c0: 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20  tine undoes the 
f6d0: 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65  effect of sqlite
f6e0: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79  3_os_init().  Ty
f6f0: 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70  pical tasks.** p
f700: 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73  erformed by thes
f710: 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75  e routines inclu
f720: 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72  de allocation or
f730: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
f740: 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75   of static resou
f750: 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61  rces, initializa
f760: 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76  tion of global v
f770: 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74  ariables,.** set
f780: 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c  ting up a defaul
f790: 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
f7a0: 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69  module, or setti
f7b0: 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75  ng up.** a defau
f7c0: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
f7d0: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
f7e0: 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a  config()]..**.**
f7f0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
f800: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e   should never in
f810: 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69  voke either sqli
f820: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
f830: 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
f840: 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  nd() directly.  
f850: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
f860: 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f  should only invo
f870: 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  ke.** sqlite3_in
f880: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73  itialize() and s
f890: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f8a0: 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ).  The sqlite3_
f8b0: 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74  os_init().** int
f8c0: 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64  erface is called
f8d0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
f8e0: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
f8f0: 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71  lize() and.** sq
f900: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69  lite3_os_end() i
f910: 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69  s called by sqli
f920: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
f930: 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20   Appropriate.** 
f940: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
f950: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  for sqlite3_os_i
f960: 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  nit() and sqlite
f970: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72  3_os_end().** ar
f980: 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  e built into SQL
f990: 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63  ite when it is c
f9a0: 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78  ompiled for Unix
f9b0: 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53  , Windows, or OS
f9c0: 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73  /2..** When [cus
f9d0: 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69  tom builds | bui
f9e0: 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61  lt for other pla
f9f0: 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e  tforms].** (usin
fa00: 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53  g the [SQLITE_OS
fa10: 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c  _OTHER=1] compil
fa20: 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
fa30: 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  ) the applicatio
fa40: 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20  n must supply a 
fa50: 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  suitable impleme
fa60: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73  ntation for.** s
fa70: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
fa80: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
fa90: 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69  end().  An appli
faa0: 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a  cation-supplied.
fab0: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
fac0: 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  n of sqlite3_os_
fad0: 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65  init() or sqlite
fae0: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75  3_os_end().** mu
faf0: 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  st return [SQLIT
fb00: 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
fb10: 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20   and some other 
fb20: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f  [error code] upo
fb30: 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f  n.** failure..*/
fb40: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69  .int sqlite3_ini
fb50: 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69  tialize(void);.i
fb60: 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nt sqlite3_shutd
fb70: 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  own(void);.int s
fb80: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76  qlite3_os_init(v
fb90: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
fba0: 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a  3_os_end(void);.
fbb0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
fbc0: 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65   Configuring The
fbd0: 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a   SQLite Library.
fbe0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
fbf0: 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
fc00: 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
fc10: 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66  make global conf
fc20: 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
fc30: 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69  nges to SQLite i
fc40: 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20  n order to tune 
fc50: 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70  SQLite to the sp
fc60: 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a  ecific needs of.
fc70: 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
fc80: 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  on.  The default
fc90: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69   configuration i
fca0: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
fcb0: 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63  r most.** applic
fcc0: 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68  ations and so th
fcd0: 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73  is routine is us
fce0: 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73  ually not necess
fcf0: 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70  ary.  It is.** p
fd00: 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f  rovided to suppo
fd10: 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74  rt rare applicat
fd20: 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61  ions with unusua
fd30: 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54  l needs..**.** T
fd40: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
fd50: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
fd60: 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e   not threadsafe.
fd70: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
fd80: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65  n.** must insure
fd90: 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53   that no other S
fda0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
fdb0: 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20   are invoked by 
fdc0: 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73  other.** threads
fdd0: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63   while sqlite3_c
fde0: 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69  onfig() is runni
fdf0: 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65  ng.  Furthermore
fe00: 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  , sqlite3_config
fe10: 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ().** may only b
fe20: 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20  e invoked prior 
fe30: 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69  to library initi
fe40: 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a  alization using.
fe50: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ** [sqlite3_init
fe60: 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  ialize()] or aft
fe70: 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b  er shutdown by [
fe80: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
fe90: 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ()]..** ^If sqli
fea0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
feb0: 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
fec0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fed0: 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a  ()] and before.*
fee0: 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
fef0: 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77  own()] then it w
ff00: 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54  ill return SQLIT
ff10: 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74  E_MISUSE..** Not
ff20: 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74  e, however, that
ff30: 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   ^sqlite3_config
ff40: 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  () can be called
ff50: 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a   as part of the.
ff60: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
ff70: 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74  n of an applicat
ff80: 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c  ion-defined [sql
ff90: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e  ite3_os_init()].
ffa0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
ffb0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
ffc0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
ffd0: 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b   an integer.** [
ffe0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
fff0: 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72  tion] that deter
10000 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72  mines.** what pr
10010 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65  operty of SQLite
10020 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67   is to be config
10030 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e  ured.  Subsequen
10040 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76  t arguments.** v
10050 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
10060 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74   the [configurat
10070 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69  ion option].** i
10080 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
10090 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  ment..**.** ^Whe
100a0 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  n a configuratio
100b0 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c  n option is set,
100c0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
100d0 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ) returns [SQLIT
100e0 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  E_OK]..** ^If th
100f0 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e  e option is unkn
10100 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73  own or SQLite is
10110 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74   unable to set t
10120 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65  he option.** the
10130 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  n this routine r
10140 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72  eturns a non-zer
10150 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  o [error code]..
10160 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
10170 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b  onfig(int, ...);
10180 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
10190 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61  : Configure data
101a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
101b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
101c0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
101d0 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
101e0 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75   to make configu
101f0 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
10200 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65  s to a [database
10210 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
10220 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  he interface is 
10230 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73  similar to.** [s
10240 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
10250 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
10260 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74   changes apply t
10270 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64  o a single.** [d
10280 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10290 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69  on] (specified i
102a0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
102b0 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment)..**.** The
102c0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
102d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
102e0 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20  onfig(D,V,...)  
102f0 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  is the.** [SQLIT
10300 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
10310 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61  SIDE | configura
10320 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20  tion verb] - an 
10330 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a  integer code .**
10340 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
10350 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74  what aspect of t
10360 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
10370 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
10380 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a  g configured..**
10390 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
103a0 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e  ments vary depen
103b0 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66  ding on the conf
103c0 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a  iguration verb..
103d0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  **.** ^Calls to 
103e0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
103f0 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54  g() return SQLIT
10400 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79  E_OK if and only
10410 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20   if.** the call 
10420 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75  is considered su
10430 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  ccessful..*/.int
10440 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
10450 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ig(sqlite3*, int
10460 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a   op, ...);../*.*
10470 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
10480 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f  ry Allocation Ro
10490 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20  utines.**.** An 
104a0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
104b0 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
104c0 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
104d0 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20  tween SQLite.** 
104e0 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  and low-level me
104f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10500 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
10510 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75  This object is u
10520 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20  sed in only one 
10530 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c  place in the SQL
10540 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
10550 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * A pointer to a
10560 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
10570 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65  is object is the
10580 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
10590 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
105a0 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66  )] when the conf
105b0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
105c0 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43   is.** [SQLITE_C
105d0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72  ONFIG_MALLOC] or
105e0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
105f0 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a  GETMALLOC].  .**
10600 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20   By creating an 
10610 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
10620 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70   object.** and p
10630 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
10640 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
10650 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
10660 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20  LOC]).** during 
10670 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61  configuration, a
10680 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61  n application ca
10690 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  n specify an alt
106a0 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
106b0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
106c0 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69  bsystem for SQLi
106d0 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c  te to use for al
106e0 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61  l of its.** dyna
106f0 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  mic memory needs
10700 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
10710 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77  t SQLite comes w
10720 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69  ith several [bui
10730 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
10740 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74  ocators].** that
10750 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61   are perfectly a
10760 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20  dequate for the 
10770 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a  overwhelming maj
10780 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
10790 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61  tions.** and tha
107a0 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  t this object is
107b0 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20   only useful to 
107c0 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20  a tiny minority 
107d0 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
107e0 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69  ** with speciali
107f0 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  zed memory alloc
10800 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e  ation requiremen
10810 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ts.  This object
10820 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64   is.** also used
10830 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
10840 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  of SQLite in ord
10850 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e  er to specify an
10860 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
10870 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
10880 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20   that simulates 
10890 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65  memory out-of-me
108a0 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20  mory conditions 
108b0 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76  in.** order to v
108c0 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74  erify that SQLit
108d0 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65  e recovers grace
108e0 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a  fully from such.
108f0 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a  ** conditions..*
10900 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63  *.** The xMalloc
10910 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20  , xRealloc, and 
10920 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75  xFree methods mu
10930 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65  st work like the
10940 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65  .** malloc(), re
10950 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
10960 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f  () functions fro
10970 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
10980 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51   library..** ^SQ
10990 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
109a0 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20  that the second 
109b0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78  argument to.** x
109c0 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79  Realloc is alway
109d0 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e  s a value return
109e0 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61  ed by a prior ca
109f0 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a  ll to xRoundup..
10a00 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75  **.** xSize shou
10a10 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c  ld return the al
10a20 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20  located size of 
10a30 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
10a40 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ion.** previousl
10a50 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
10a60 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c  xMalloc or xReal
10a70 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61  loc.  The alloca
10a80 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61  ted size.** is a
10a90 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61  lways at least a
10aa0 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71  s big as the req
10ab0 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20  uested size but 
10ac0 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a  may be larger..*
10ad0 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75  *.** The xRoundu
10ae0 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  p method returns
10af0 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74   what would be t
10b00 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
10b10 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79  e of.** a memory
10b20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65   allocation give
10b30 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  n a particular r
10b40 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20  equested size.  
10b50 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  Most memory.** a
10b60 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
10b70 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  up memory alloca
10b80 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74  tions at least t
10b90 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69  o the next multi
10ba0 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f  ple.** of 8.  So
10bb0 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  me allocators ro
10bc0 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67  und up to a larg
10bd0 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74  er multiple or t
10be0 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a  o a power of 2..
10bf0 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20  ** Every memory 
10c00 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65  allocation reque
10c10 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72  st coming in thr
10c20 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61  ough [sqlite3_ma
10c30 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  lloc()].** or [s
10c40 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
10c50 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52  ] first calls xR
10c60 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75  oundup.  If xRou
10c70 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20  ndup returns 0, 
10c80 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20  .** that causes 
10c90 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
10ca0 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  g memory allocat
10cb0 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a  ion to fail..**.
10cc0 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
10cd0 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
10ce0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
10cf0 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d 70  ator.  For examp
10d00 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20  le,.** it might 
10d10 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71  allocate any req
10d20 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20  uire mutexes or 
10d30 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72  initialize inter
10d40 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75  nal data.** stru
10d50 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68  ctures.  The xSh
10d60 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
10d70 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65   invoked (indire
10d80 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c  ctly) by.** [sql
10d90 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
10da0 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c   and should deal
10db0 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75  locate any resou
10dc0 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a  rces acquired.**
10dd0 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20   by xInit.  The 
10de0 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72  pAppData pointer
10df0 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
10e00 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
10e10 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78  o.** xInit and x
10e20 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20  Shutdown..**.** 
10e30 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65  SQLite holds the
10e40 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53   [SQLITE_MUTEX_S
10e50 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75  TATIC_MASTER] mu
10e60 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f  tex when it invo
10e70 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74  kes.** the xInit
10e80 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20   method, so the 
10e90 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65  xInit method nee
10ea0 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73  d not be threads
10eb0 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68  afe.  The.** xSh
10ec0 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
10ed0 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f   only called fro
10ee0 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  m [sqlite3_shutd
10ef0 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65  own()] so it doe
10f00 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f  s.** not need to
10f10 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65   be threadsafe e
10f20 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20  ither.  For all 
10f30 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53  other methods, S
10f40 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74  QLite.** holds t
10f50 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
10f60 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74  _STATIC_MEM] mut
10f70 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ex as long as th
10f80 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e.** [SQLITE_CON
10f90 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63  FIG_MEMSTATUS] c
10fa0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10fb0 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e  ion is turned on
10fc0 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73   (which.** it is
10fd0 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64   by default) and
10fe0 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20   so the methods 
10ff0 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
11000 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a  y serialized..**
11010 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51   However, if [SQ
11020 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
11030 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c  TATUS] is disabl
11040 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68  ed, then the oth
11050 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75  er.** methods mu
11060 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
11070 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68   or else make th
11080 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d  eir own arrangem
11090 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69  ents for.** seri
110a0 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  alization..**.**
110b0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76   SQLite will nev
110c0 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28  er invoke xInit(
110d0 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  ) more than once
110e0 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65   without an inte
110f0 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20  rvening.** call 
11100 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a  to xShutdown()..
11110 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
11120 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
11130 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65  thods sqlite3_me
11140 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  m_methods;.struc
11150 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
11160 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a  thods {.  void *
11170 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b  (*xMalloc)(int);
11180 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f           /* Memo
11190 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75  ry allocation fu
111a0 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  nction */.  void
111b0 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29   (*xFree)(void*)
111c0 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72  ;          /* Fr
111d0 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63  ee a prior alloc
111e0 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ation */.  void 
111f0 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69  *(*xRealloc)(voi
11200 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73  d*,int);  /* Res
11210 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f  ize an allocatio
11220 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69  n */.  int (*xSi
11230 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ze)(void*);     
11240 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20        /* Return 
11250 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61  the size of an a
11260 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
11270 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69  nt (*xRoundup)(i
11280 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  nt);          /*
11290 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73   Round up reques
112a0 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61  t size to alloca
112b0 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69  tion size */.  i
112c0 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64  nt (*xInit)(void
112d0 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
112e0 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   Initialize the 
112f0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
11300 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68   */.  void (*xSh
11310 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20  utdown)(void*); 
11320 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61       /* Deinitia
11330 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
11340 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
11350 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
11360 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
11370 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e   Argument to xIn
11380 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f  it() and xShutdo
11390 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  wn() */.};../*.*
113a0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
113b0 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  iguration Option
113c0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
113d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
113e0 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion}.**.** Thes
113f0 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
11400 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
11410 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
11420 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
11430 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
11440 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
11450 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
11460 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11470 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
11480 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61  ** New configura
11490 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79  tion options may
114a0 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
114b0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
114c0 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74  SQLite..** Exist
114d0 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
114e0 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20  n options might 
114f0 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e  be discontinued.
11500 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a    Applications.*
11510 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74  * should check t
11520 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66  he return code f
11530 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  rom [sqlite3_con
11540 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
11550 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
11560 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68  call worked.  Th
11570 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
11580 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  g()] interface w
11590 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  ill return a.** 
115a0 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
115b0 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f  code] if a disco
115c0 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70  ntinued or unsup
115d0 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61  ported configura
115e0 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69  tion option.** i
115f0 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
11600 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
11610 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
11620 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49  HREAD]] <dt>SQLI
11630 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
11640 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
11650 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
11660 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
11670 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
11680 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
11690 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
116a0 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74  ode] to Single-t
116b0 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72  hread.  In other
116c0 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62   words, it disab
116d0 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78  les.** all mutex
116e0 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c  ing and puts SQL
116f0 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20  ite into a mode 
11700 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c  where it can onl
11710 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20  y be used.** by 
11720 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  a single thread.
11730 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
11740 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
11750 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
11760 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
11770 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
11780 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
11790 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
117a0 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
117b0 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68  o change the [th
117c0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72  reading mode] fr
117d0 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a  om its default.*
117e0 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c  * value of Singl
117f0 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20  e-thread and so 
11800 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
11810 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a  )] will return .
11820 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
11830 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
11840 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
11850 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a  IG_SINGLETHREAD.
11860 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
11870 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
11880 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
11890 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
118a0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
118b0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c  FIG_MULTITHREAD<
118c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
118d0 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
118e0 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
118f0 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
11900 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
11910 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
11920 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20   Multi-thread.  
11930 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
11940 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d  it disables.** m
11950 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61  utexing on [data
11960 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
11970 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
11980 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
11990 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  s..** The applic
119a0 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73  ation is respons
119b0 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69  ible for seriali
119c0 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a  zing access to.*
119d0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
119e0 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
119f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
11a00 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d  s].  But other m
11a10 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
11a20 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51  abled so that SQ
11a30 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66  Lite will be saf
11a40 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75  e to use in a mu
11a50 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  lti-threaded.** 
11a60 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c  environment as l
11a70 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68  ong as no two th
11a80 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f  reads attempt to
11a90 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a   use the same.**
11aa0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11ab0 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61  ction] at the sa
11ac0 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51  me time.  ^If SQ
11ad0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
11ae0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
11af0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
11b00 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
11b10 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
11b20 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
11b30 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
11b40 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
11b50 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   Multi-thread [t
11b60 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
11b70 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
11b80 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
11b90 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
11ba0 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
11bb0 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
11bc0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
11bd0 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  EAD configuratio
11be0 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
11bf0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
11c00 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d  NFIG_SERIALIZED]
11c10 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
11c20 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f  FIG_SERIALIZED</
11c30 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
11c40 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
11c50 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
11c60 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
11c70 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
11c80 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
11c90 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f  Serialized. In o
11ca0 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73  ther words, this
11cb0 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a   option enables.
11cc0 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69  ** all mutexes i
11cd0 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63  ncluding the rec
11ce0 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65  ursive.** mutexe
11cf0 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
11d00 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
11d10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
11d20 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
11d30 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68  In this mode (wh
11d40 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75  ich is the defau
11d50 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  lt when SQLite i
11d60 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
11d70 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  ** [SQLITE_THREA
11d80 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51  DSAFE=1]) the SQ
11d90 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c  Lite library wil
11da0 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69  l itself seriali
11db0 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ze access.** to 
11dc0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11dd0 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70  tions] and [prep
11de0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
11df0 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20   so that the.** 
11e00 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66  application is f
11e10 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73  ree to use the s
11e20 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
11e30 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65  nnection] or the
11e40 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72  .** same [prepar
11e50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
11e60 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
11e70 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ds at the same t
11e80 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69  ime..** ^If SQLi
11e90 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
11ea0 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
11eb0 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
11ec0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
11ed0 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
11ee0 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
11ef0 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
11f00 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53  ble to set the S
11f10 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
11f20 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
11f30 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
11f40 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
11f50 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
11f60 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
11f70 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
11f80 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63  FIG_SERIALIZED c
11f90 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11fa0 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
11fb0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
11fc0 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c  MALLOC]] <dt>SQL
11fd0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
11fe0 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  C</dt>.** <dd> ^
11ff0 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
12000 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
12010 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
12020 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
12030 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
12040 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
12050 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
12060 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
12070 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74  specifies.** alt
12080 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
12090 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
120a0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f  tion routines to
120b0 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63   be used in plac
120c0 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  e of.** the memo
120d0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
120e0 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
120f0 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c  o SQLite.)^ ^SQL
12100 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73  ite makes.** its
12110 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
12120 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74  y of the content
12130 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
12140 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
12150 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72  ructure.** befor
12160 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  e the [sqlite3_c
12170 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65  onfig()] call re
12180 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  turns.</dd>.**.*
12190 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
121a0 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  G_GETMALLOC]] <d
121b0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
121c0 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  GETMALLOC</dt>.*
121d0 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
121e0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
121f0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
12200 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
12210 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
12220 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
12230 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
12240 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b  tructure.  The [
12250 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
12260 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
12270 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
12280 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
12290 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c  efined memory al
122a0 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
122b0 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
122c0 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
122d0 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
122e0 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
122f0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
12300 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
12310 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61  pper that simula
12320 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  tions memory all
12330 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20  ocation failure 
12340 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d  or.** tracks mem
12350 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65  ory usage, for e
12360 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  xample. </dd>.**
12370 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12380 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20  FIG_MEMSTATUS]] 
12390 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
123a0 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e  G_MEMSTATUS</dt>
123b0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
123c0 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67  ption takes sing
123d0 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  le argument of t
123e0 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72  ype int, interpr
123f0 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f  eted as a .** bo
12400 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61  olean, which ena
12410 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
12420 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20   the collection 
12430 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  of memory alloca
12440 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74  tion .** statist
12450 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f  ics. ^(When memo
12460 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
12470 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73  atistics are dis
12480 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66  abled, the .** f
12490 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20  ollowing SQLite 
124a0 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d  interfaces becom
124b0 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61  e non-operationa
124c0 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20  l:.**   <ul>.** 
124d0 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
124e0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a  memory_used()].*
124f0 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
12500 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
12510 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  er()].**   <li> 
12520 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
12530 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a  ap_limit64()].**
12540 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
12550 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20  _status()].**   
12560 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f  </ul>)^.** ^Memo
12570 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
12580 61 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61  atistics are ena
12590 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
125a0 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73  unless SQLite is
125b0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  .** compiled wit
125c0 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c  h [SQLITE_DEFAUL
125d0 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69  T_MEMSTATUS]=0 i
125e0 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d  n which case mem
125f0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
12600 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
12610 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
12620 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  ault..** </dd>.*
12630 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12640 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c  NFIG_SCRATCH]] <
12650 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12660 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a  _SCRATCH</dt>.**
12670 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
12680 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
12690 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
126a0 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
126b0 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73  can use for.** s
126c0 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20  cratch memory.  
126d0 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
126e0 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f  arguments:  A po
126f0 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a  inter an 8-byte.
12700 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72  ** aligned memor
12710 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68  y buffer from wh
12720 69 63 68 20 74 68 65 20 73 63 72 61 74 63 68 20  ich the scratch 
12730 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c  allocations will
12740 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68   be.** drawn, th
12750 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73  e size of each s
12760 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
12770 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74  n (sz),.** and t
12780 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
12790 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c  r of scratch all
127a0 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54  ocations (N).  T
127b0 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e  he sz.** argumen
127c0 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74  t must be a mult
127d0 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54  iple of 16..** T
127e0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
127f0 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e  t must be a poin
12800 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ter to an 8-byte
12810 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a   aligned buffer.
12820 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  ** of at least s
12830 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
12840 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ory..** ^SQLite 
12850 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65  will use no more
12860 20 74 68 61 6e 20 74 77 6f 20 73 63 72 61 74 63   than two scratc
12870 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68  h buffers per th
12880 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73  read.  So.** N s
12890 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20  hould be set to 
128a0 74 77 69 63 65 20 74 68 65 20 65 78 70 65 63 74  twice the expect
128b0 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  ed maximum numbe
128c0 72 20 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a  r of threads..**
128d0 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65   ^SQLite will ne
128e0 76 65 72 20 72 65 71 75 69 72 65 20 61 20 73 63  ver require a sc
128f0 72 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61  ratch buffer tha
12900 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36  t is more than 6
12910 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61  .** times the da
12920 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65  tabase page size
12930 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65  . ^If SQLite nee
12940 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f  ds needs additio
12950 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d  nal.** scratch m
12960 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61  emory beyond wha
12970 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  t is provided by
12980 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74   this configurat
12990 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  ion option, then
129a0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
129b0 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20  lloc()] will be 
129c0 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
129d0 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64  he memory needed
129e0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
129f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
12a00 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c  ECACHE]] <dt>SQL
12a10 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
12a20 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ACHE</dt>.** <dd
12a30 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  > ^This option s
12a40 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
12a50 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
12a60 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
12a70 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64  use for.** the d
12a80 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63  atabase page cac
12a90 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61  he with the defa
12aa0 75 6c 74 20 70 61 67 65 20 63 61 63 68 65 20 69  ult page cache i
12ab0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
12ac0 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75  .** This configu
12ad0 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f  ration should no
12ae0 74 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20  t be used if an 
12af0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
12b00 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65  ne page.** cache
12b10 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
12b20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20  is loaded using 
12b30 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
12b40 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e  G_PCACHE2 option
12b50 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  ..** There are t
12b60 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74  hree arguments t
12b70 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41  o this option: A
12b80 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79   pointer to 8-by
12b90 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65  te aligned.** me
12ba0 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f  mory, the size o
12bb0 66 20 65 61 63 68 20 70 61 67 65 20 62 75 66 66  f each page buff
12bc0 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65  er (sz), and the
12bd0 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73   number of pages
12be0 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20   (N)..** The sz 
12bf0 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
12c00 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  be the size of t
12c10 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62  he largest datab
12c20 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70  ase page.** (a p
12c30 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77  ower of two betw
12c40 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36  een 512 and 3276
12c50 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 65  8) plus a little
12c60 20 65 78 74 72 61 20 66 6f 72 20 65 61 63 68 0a   extra for each.
12c70 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20  ** page header. 
12c80 20 5e 54 68 65 20 70 61 67 65 20 68 65 61 64 65   ^The page heade
12c90 72 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f 20  r size is 20 to 
12ca0 34 30 20 62 79 74 65 73 20 64 65 70 65 6e 64 69  40 bytes dependi
12cb0 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73  ng on.** the hos
12cc0 74 20 61 72 63 68 69 74 65 63 74 75 72 65 2e 20  t architecture. 
12cd0 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73   ^It is harmless
12ce0 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65  , apart from the
12cf0 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a   wasted memory,.
12d00 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20  ** to make sz a 
12d10 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65  little too large
12d20 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20  .  The first.** 
12d30 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
12d40 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f  point to an allo
12d50 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61  cation of at lea
12d60 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
12d70 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c   memory..** ^SQL
12d80 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65  ite will use the
12d90 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64   memory provided
12da0 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72   by the first ar
12db0 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66  gument to satisf
12dc0 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20  y its.** memory 
12dd0 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69  needs for the fi
12de0 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74  rst N pages that
12df0 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68   it adds to cach
12e00 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e  e.  ^If addition
12e10 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  al.** page cache
12e20 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65   memory is neede
12e30 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  d beyond what is
12e40 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
12e50 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a  s option, then.*
12e60 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f  * SQLite goes to
12e70 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
12e80 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69  ()] for the addi
12e90 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73  tional storage s
12ea0 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69  pace..** The poi
12eb0 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69 72 73  nter in the firs
12ec0 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a  t argument must.
12ed0 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  ** be aligned to
12ee0 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64   an 8-byte bound
12ef0 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
12f00 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
12f10 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  Lite.** will be 
12f20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a  undefined.</dd>.
12f30 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
12f40 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74  ONFIG_HEAP]] <dt
12f50 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  >SQLITE_CONFIG_H
12f60 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAP</dt>.** <dd>
12f70 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70   ^This option sp
12f80 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
12f90 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
12fa0 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
12fb0 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f  use.** for all o
12fc0 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65  f its dynamic me
12fd0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12fe0 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f  needs beyond tho
12ff0 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66  se provided.** f
13000 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f  or by [SQLITE_CO
13010 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e  NFIG_SCRATCH] an
13020 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  d [SQLITE_CONFIG
13030 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
13040 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
13050 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d  arguments: An 8-
13060 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69  byte aligned poi
13070 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f  nter to the memo
13080 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  ry,.** the numbe
13090 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
130a0 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c  e memory buffer,
130b0 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d   and the minimum
130c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
130d0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72  ..** ^If the fir
130e0 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20  st pointer (the 
130f0 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20  memory pointer) 
13100 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51  is NULL, then SQ
13110 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20  Lite reverts.** 
13120 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66  to using its def
13130 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
13140 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65  cator (the syste
13150 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65  m malloc() imple
13160 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75  mentation),.** u
13170 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72  ndoing any prior
13180 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
13190 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
131a0 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a  LLOC].  ^If the.
131b0 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  ** memory pointe
131c0 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e  r is not NULL an
131d0 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  d either [SQLITE
131e0 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d  _ENABLE_MEMSYS3]
131f0 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45   or.** [SQLITE_E
13200 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61  NABLE_MEMSYS5] a
13210 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e  re defined, then
13220 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65   the alternative
13230 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
13240 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20  ator is engaged 
13250 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66  to handle all of
13260 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20   SQLites memory 
13270 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
13280 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  ..** The first p
13290 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
132a0 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74  ry pointer) must
132b0 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
132c0 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e  n 8-byte.** boun
132d0 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65  dary or subseque
132e0 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  nt behavior of S
132f0 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e  QLite will be un
13300 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  defined..** The 
13310 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
13320 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65  on size is cappe
13330 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73  d at 2**12. Reas
13340 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a  onable values.**
13350 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d   for the minimum
13360 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
13370 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67   are 2**5 throug
13380 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a  h 2**8.</dd>.**.
13390 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
133a0 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  IG_MUTEX]] <dt>S
133b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
133c0 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
133d0 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
133e0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
133f0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
13400 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
13410 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
13420 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
13430 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
13440 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ure.  The argume
13450 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
13460 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
13470 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74  level mutex rout
13480 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
13490 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20  in place.** the 
134a0 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62  mutex routines b
134b0 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
134c0 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b  .)^  ^SQLite mak
134d0 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
134e0 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  .** content of t
134f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
13500 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
13510 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20  ture before the 
13520 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
13530 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65  te3_config()] re
13540 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74  turns. ^If SQLit
13550 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
13560 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
13570 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
13580 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
13590 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
135a0 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
135b0 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
135c0 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
135d0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
135e0 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
135f0 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
13600 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
13610 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
13620 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f  _CONFIG_MUTEX co
13630 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13640 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  on will.** retur
13650 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
13660 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
13670 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
13680 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
13690 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
136a0 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
136b0 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
136c0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
136d0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
136e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
136f0 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
13700 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
13710 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
13720 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  ure.  The.** [sq
13730 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
13740 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
13750 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
13760 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
13770 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75  efined mutex rou
13780 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73  tines.)^.** This
13790 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
137a0 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
137b0 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65  the default mute
137c0 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  x allocation.** 
137d0 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
137e0 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20  wrapper used to 
137f0 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67  track mutex usag
13800 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63  e for performanc
13810 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f  e.** profiling o
13820 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65  r testing, for e
13830 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51  xample.   ^If SQ
13840 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
13850 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
13860 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
13870 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
13880 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
13890 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
138a0 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
138b0 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
138c0 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
138d0 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
138e0 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
138f0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
13900 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
13910 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
13920 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  TEX configuratio
13930 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a  n option will.**
13940 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
13950 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ERROR].</dd>.**.
13960 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
13970 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c  IG_LOOKASIDE]] <
13980 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
13990 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
139a0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
139b0 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
139c0 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
139d0 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66  etermine the def
139e0 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  ault.** memory a
139f0 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74 68  llocation for th
13a00 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
13a10 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20  ry allocator on 
13a20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73  each.** [databas
13a30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
13a40 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
13a50 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
13a60 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
13a70 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20  ide buffer slot 
13a80 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69  and the second i
13a90 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
13aa0 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74  ** slots allocat
13ab0 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ed to each datab
13ac0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29  ase connection.)
13ad0 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  ^  ^(This option
13ae0 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e   sets the.** <i>
13af0 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b  default</i> look
13b00 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20  aside size. The 
13b10 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  [SQLITE_DBCONFIG
13b20 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76  _LOOKASIDE].** v
13b30 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  erb to [sqlite3_
13b40 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e  db_config()] can
13b50 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e   be used to chan
13b60 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
13b70 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
13b80 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
13b90 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c  connections.)^ <
13ba0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13bb0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
13bc0 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  E2]] <dt>SQLITE_
13bd0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f  CONFIG_PCACHE2</
13be0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
13bf0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
13c00 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
13c10 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
13c20 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73  nter to.** an [s
13c30 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
13c40 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20  thods2] object. 
13c50 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65   This object spe
13c60 63 69 66 69 65 73 20 74 68 65 20 69 6e 74 65 72  cifies the inter
13c70 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73  face.** to a cus
13c80 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69  tom page cache i
13c90 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e  mplementation.)^
13ca0 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20    ^SQLite makes 
13cb0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
13cc0 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73   object and uses
13cd0 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 61 63   it for page cac
13ce0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
13cf0 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  tions.</dd>.**.*
13d00 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13d10 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c  G_GETPCACHE2]] <
13d20 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
13d30 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e  _GETPCACHE2</dt>
13d40 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
13d50 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
13d60 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
13d70 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
13d80 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  r to an.** [sqli
13d90 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
13da0 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51  ds2] object.  SQ
13db0 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74  Lite copies of t
13dc0 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61  he current.** pa
13dd0 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
13de0 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61  ntation into tha
13df0 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64  t object.)^ </dd
13e00 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
13e10 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64  _CONFIG_LOG]] <d
13e20 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13e30 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOG</dt>.** <dd>
13e40 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   The SQLITE_CONF
13e50 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73  IG_LOG option is
13e60 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75   used to configu
13e70 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a  re the SQLite.**
13e80 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c   global [error l
13e90 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51  og]..** (^The SQ
13ea0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
13eb0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
13ec0 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f   arguments: a po
13ed0 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75  inter to a.** fu
13ee0 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61  nction with a ca
13ef0 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20  ll signature of 
13f00 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e  void(*)(void*,in
13f10 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  t,const char*), 
13f20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65  .** and a pointe
13f30 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74  r to void. ^If t
13f40 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  he function poin
13f50 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  ter is not NULL,
13f60 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65   it is.** invoke
13f70 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  d by [sqlite3_lo
13f80 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20  g()] to process 
13f90 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65  each logging eve
13fa0 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  nt.  ^If the.** 
13fb0 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
13fc0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73   is NULL, the [s
13fd0 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e  qlite3_log()] in
13fe0 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20  terface becomes 
13ff0 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65  a no-op..** ^The
14000 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68   void pointer th
14010 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64  at is the second
14020 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c   argument to SQL
14030 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69  ITE_CONFIG_LOG i
14040 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f  s.** passed thro
14050 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74  ugh as the first
14060 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
14070 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
14080 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
14090 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65  function wheneve
140a0 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20  r that function 
140b0 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68  is invoked.  ^Th
140c0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
140d0 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67  er to.** the log
140e0 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ger function is 
140f0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69  a copy of the fi
14100 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
14110 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
14120 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  ng.** [sqlite3_l
14130 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69  og()] call and i
14140 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65  s intended to be
14150 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d   a [result code]
14160 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e   or an.** [exten
14170 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
14180 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  .  ^The third pa
14190 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74  rameter passed t
141a0 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a  o the logger is.
141b0 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61  ** log message a
141c0 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20  fter formatting 
141d0 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  via [sqlite3_snp
141e0 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65  rintf()]..** The
141f0 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20   SQLite logging 
14200 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
14210 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20   reentrant; the 
14220 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a  logger function.
14230 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20 74  ** supplied by t
14240 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
14250 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61  ust not invoke a
14260 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ny SQLite interf
14270 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c  ace..** In a mul
14280 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c  ti-threaded appl
14290 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70  ication, the app
142a0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
142b0 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74   logger.** funct
142c0 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65  ion must be thre
142d0 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  adsafe. </dd>.**
142e0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
142f0 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51  FIG_URI]] <dt>SQ
14300 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a  LITE_CONFIG_URI.
14310 2a 2a 20 3c 64 64 3e 5e 28 54 68 69 73 20 6f 70  ** <dd>^(This op
14320 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
14330 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
14340 74 79 70 65 20 69 6e 74 2e 20 49 66 20 6e 6f 6e  type int. If non
14350 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55  -zero, then.** U
14360 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
14370 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e  lobally enabled.
14380 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   If the paramete
14390 72 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20  r is zero, then 
143a0 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20  URI handling.** 
143b0 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61  is globally disa
143c0 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 49 20  bled.)^ ^If URI 
143d0 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
143e0 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20 61 6c  ally enabled, al
143f0 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70  l filenames.** p
14400 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
14410 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
14420 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
14430 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
14440 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69  )] or.** specifi
14450 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41  ed as part of [A
14460 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20  TTACH] commands 
14470 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
14480 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c  as URIs, regardl
14490 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65  ess.** of whethe
144a0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51  r or not the [SQ
144b0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
144c0 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
144d0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
144e0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
144f0 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69 73 20  ened. ^If it is 
14500 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65  globally disable
14510 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65  d, filenames are
14520 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72  .** only interpr
14530 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20  eted as URIs if 
14540 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
14550 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20  URI flag is set 
14560 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61  when the.** data
14570 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
14580 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20  is opened. ^(By 
14590 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e  default, URI han
145a0 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
145b0 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54  y.** disabled. T
145c0 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
145d0 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20   may be changed 
145e0 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74  by compiling wit
145f0 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
14600 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c  _USE_URI] symbol
14610 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a   defined.)^.**.*
14620 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14630 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
14640 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49  _SCAN]] <dt>SQLI
14650 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
14660 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a  NG_INDEX_SCAN.**
14670 20 3c 64 64 3e 5e 54 68 69 73 20 6f 70 74 69 6f   <dd>^This optio
14680 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
14690 20 69 6e 74 65 67 65 72 20 61 72 67 75 6d 65 6e   integer argumen
146a0 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 72  t which is inter
146b0 70 72 65 74 65 64 20 61 73 0a 2a 2a 20 61 20 62  preted as.** a b
146c0 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20  oolean in order 
146d0 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
146e0 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20  able the use of 
146f0 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73  covering indices
14700 20 66 6f 72 0a 2a 2a 20 66 75 6c 6c 20 74 61 62   for.** full tab
14710 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20  le scans in the 
14720 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e  query optimizer.
14730 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73    ^The default s
14740 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d  etting is determ
14750 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b  ined.** by the [
14760 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56  SQLITE_ALLOW_COV
14770 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
14780 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
14790 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e  ption, or is "on
147a0 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d  ".** if that com
147b0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
147c0 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20   is omitted..** 
147d0 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64  The ability to d
147e0 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f  isable the use o
147f0 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63  f covering indic
14800 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c  es for full tabl
14810 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65  e scans.** is be
14820 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72  cause some incor
14830 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67  rectly coded leg
14840 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  acy applications
14850 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69   might malfuncti
14860 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f  on.** when the o
14870 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65  ptimization is e
14880 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69  nabled.  Providi
14890 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 74  ng the ability t
148a0 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65  o.** disable the
148b0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c   optimization al
148c0 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20  lows the older, 
148d0 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f  buggy applicatio
148e0 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a  n code to work.*
148f0 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65  * without change
14900 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72   even with newer
14910 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
14920 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ite..**.** [[SQL
14930 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
14940 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  E]] [[SQLITE_CON
14950 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a  FIG_GETPCACHE]].
14960 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
14970 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20  NFIG_PCACHE and 
14980 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
14990 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20  TPCACHE.** <dd> 
149a0 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72  These options ar
149b0 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73  e obsolete and s
149c0 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65  hould not be use
149d0 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a  d by new code..*
149e0 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69  * They are retai
149f0 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ned for backward
14a00 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
14a10 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f  but are now no-o
14a20 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  ps..** </dd>.**.
14a30 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14a40 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c  IG_SQLLOG]].** <
14a50 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14a60 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54  _SQLLOG.** <dd>T
14a70 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e  his option is on
14a80 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
14a90 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  sqlite is compil
14aa0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
14ab0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51  SQLITE_ENABLE_SQ
14ac0 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73  LLOG] pre-proces
14ad0 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65  sor macro define
14ae0 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67  d. The first arg
14af0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20  ument should.** 
14b00 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
14b10 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79  a function of ty
14b20 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  pe void(*)(void*
14b30 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20  ,sqlite3*,const 
14b40 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20  char*, int)..** 
14b50 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c  The second shoul
14b60 64 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f  d be of type (vo
14b70 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61  id*). The callba
14b80 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79  ck is invoked by
14b90 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20   the library.** 
14ba0 69 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 74  in three separat
14bb0 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c  e circumstances,
14bc0 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
14bd0 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  he value passed 
14be0 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68  as the.** fourth
14bf0 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74   parameter. If t
14c00 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
14c10 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74  ter is 0, then t
14c20 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
14c30 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64  ection.** passed
14c40 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
14c50 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74  rgument has just
14c60 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68   been opened. Th
14c70 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
14c80 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20  .** points to a 
14c90 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e  buffer containin
14ca0 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  g the name of th
14cb0 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20  e main database 
14cc0 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20  file. If the.** 
14cd0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
14ce0 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20   is 1, then the 
14cf0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68  SQL statement th
14d00 61 74 20 74 68 65 20 74 68 69 72 64 20 70 61 72  at the third par
14d10 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73  ameter.** points
14d20 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65   to has just bee
14d30 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20  n executed. Or, 
14d40 69 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  if the fourth pa
14d50 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68  rameter is 2, th
14d60 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63  en.** the connec
14d70 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65  tion being passe
14d80 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
14d90 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 69  parameter is bei
14da0 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a  ng closed. The.*
14db0 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  * third paramete
14dc0 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c  r is passed NULL
14dd0 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20   In this case.  
14de0 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73  An example of us
14df0 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66  ing this.** conf
14e00 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
14e10 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20   can be seen in 
14e20 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67  the "test_sqllog
14e30 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20  .c" source file 
14e40 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69  in.** the canoni
14e50 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63  cal SQLite sourc
14e60 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a  e tree.</dd>.**.
14e70 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14e80 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a  IG_MMAP_SIZE]].*
14e90 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
14ea0 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a  FIG_MMAP_SIZE.**
14eb0 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e   <dd>^SQLITE_CON
14ec0 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61  FIG_MMAP_SIZE ta
14ed0 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69  kes two 64-bit i
14ee0 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f  nteger (sqlite3_
14ef0 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a  int64) values.**
14f00 20 74 68 61 74 20 61 72 65 20 74 68 65 20 64 65   that are the de
14f10 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20  fault mmap size 
14f20 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66 61 75  limit (the defau
14f30 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a  lt setting for.*
14f40 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  * [PRAGMA mmap_s
14f50 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61  ize]) and the ma
14f60 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d  ximum allowed mm
14f70 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a  ap size limit..*
14f80 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73  * ^The default s
14f90 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76  etting can be ov
14fa0 65 72 72 69 64 64 65 6e 20 62 79 20 65 61 63 68  erridden by each
14fb0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
14fc0 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69  tion using.** ei
14fd0 74 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41  ther the [PRAGMA
14fe0 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d   mmap_size] comm
14ff0 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67  and, or by using
15000 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
15010 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
15020 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20   file control.  
15030 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c  ^(The maximum al
15040 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a  lowed mmap size.
15050 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61  ** cannot be cha
15060 6e 67 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65  nged at run-time
15070 2e 20 20 4e 6f 72 20 6d 61 79 20 74 68 65 20 6d  .  Nor may the m
15080 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
15090 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 65 78 63 65  map size.** exce
150a0 65 64 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74  ed the compile-t
150b0 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70  ime maximum mmap
150c0 20 73 69 7a 65 20 73 65 74 20 62 79 20 74 68 65   size set by the
150d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f  .** [SQLITE_MAX_
150e0 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69  MMAP_SIZE] compi
150f0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29  le-time option.)
15100 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 72 20  ^.** ^If either 
15110 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73  argument to this
15120 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 74   option is negat
15130 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20 61  ive, then that a
15140 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68  rgument is.** ch
15150 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f 6d  anged to its com
15160 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c  pile-time defaul
15170 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  t..**.** [[SQLIT
15180 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
15190 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74  EAPSIZE]].** <dt
151a0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57  >SQLITE_CONFIG_W
151b0 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a  IN32_HEAPSIZE.**
151c0 20 3c 64 64 3e 5e 54 68 69 73 20 6f 70 74 69 6f   <dd>^This optio
151d0 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
151e0 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73  ble if SQLite is
151f0 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 69   compiled for Wi
15200 6e 64 6f 77 73 0a 2a 2a 20 77 69 74 68 20 74 68  ndows.** with th
15210 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f  e [SQLITE_WIN32_
15220 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63  MALLOC] pre-proc
15230 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69  essor macro defi
15240 6e 65 64 2e 0a 2a 2a 20 53 51 4c 49 54 45 5f 43  ned..** SQLITE_C
15250 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
15260 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d  SIZE takes a 32-
15270 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  bit unsigned int
15280 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68  eger value.** th
15290 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65  at specifies the
152a0 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
152b0 20 74 68 65 20 63 72 65 61 74 65 64 20 68 65 61   the created hea
152c0 70 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  p..** </dl>.*/.#
152d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
152e0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
152f0 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a  D  1  /* nil */.
15300 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15310 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
15320 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f  D   2  /* nil */
15330 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15340 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
15350 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a  D    3  /* nil *
15360 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15370 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20  _CONFIG_MALLOC  
15380 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69        4  /* sqli
15390 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
153a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
153b0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
153c0 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71  LOC     5  /* sq
153d0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
153e0 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
153f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
15400 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20  TCH       6  /* 
15410 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
15420 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
15430 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
15440 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f  GECACHE     7  /
15450 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
15460 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
15470 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15480 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20  HEAP          8 
15490 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e   /* void*, int n
154a0 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f  Byte, int min */
154b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
154c0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
154d0 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65       9  /* boole
154e0 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  an */.#define SQ
154f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
15500 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20  X        10  /* 
15510 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
15520 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
15530 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15540 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20  GETMUTEX     11 
15550 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
15560 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a  x_methods* */./*
15570 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49   previously SQLI
15580 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41  TE_CONFIG_CHUNKA
15590 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73  LLOC 12 which is
155a0 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20   now unused. */ 
155b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
155c0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
155d0 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69      13  /* int i
155e0 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
155f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
15600 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20  HE       14  /* 
15610 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65  no-op */.#define
15620 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
15630 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20  ETPCACHE    15  
15640 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
15650 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15660 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31  G_LOG          1
15670 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69  6  /* xFunc, voi
15680 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d* */.#define SQ
15690 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20  LITE_CONFIG_URI 
156a0 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20           17  /* 
156b0 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
156c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
156d0 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a  CHE2      18  /*
156e0 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
156f0 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65  methods2* */.#de
15700 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15710 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20 20  IG_GETPCACHE2   
15720 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  19  /* sqlite3_p
15730 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20  cache_methods2* 
15740 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15750 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e  E_CONFIG_COVERIN
15760 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20  G_INDEX_SCAN 20 
15770 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69   /* int */.#defi
15780 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15790 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31  _SQLLOG       21
157a0 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f    /* xSqllog, vo
157b0 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  id* */.#define S
157c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
157d0 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a  P_SIZE    22  /*
157e0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20   sqlite3_int64, 
157f0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f  sqlite3_int64 */
15800 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15810 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
15820 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 20 2f  PSIZE      23  /
15830 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 0a  * int nByte */..
15840 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
15850 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
15860 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  ion Configuratio
15870 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  n Options.**.** 
15880 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
15890 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
158a0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
158b0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
158c0 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
158d0 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
158e0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
158f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  the [sqlite3_db_
15900 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
15910 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
15920 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
15930 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
15940 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
15950 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
15960 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
15970 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
15980 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
15990 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
159a0 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
159b0 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
159c0 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
159d0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
159e0 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
159f0 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
15a00 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73  worked.  ^The [s
15a10 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
15a20 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
15a30 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
15a40 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
15a50 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
15a60 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
15a70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
15a80 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
15a90 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
15aa0 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
15ab0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
15ac0 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
15ad0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
15ae0 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69  takes three addi
15af0 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
15b00 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
15b10 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69  the .** [lookasi
15b20 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
15b30 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  tor] configurati
15b40 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61  on for the [data
15b50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
15b60 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
15b70 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68  argument (the th
15b80 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
15b90 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
15ba0 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70  fig()] is a.** p
15bb0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
15bc0 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65  ry buffer to use
15bd0 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   for lookaside m
15be0 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66  emory..** ^The f
15bf0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66  irst argument af
15c00 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44  ter the SQLITE_D
15c10 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
15c20 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65  E verb.** may be
15c30 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63   NULL in which c
15c40 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  ase SQLite will 
15c50 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20  allocate the.** 
15c60 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
15c70 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73   itself using [s
15c80 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
15c90 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  . ^The second ar
15ca0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
15cb0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
15cc0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
15cd0 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64  lot.  ^The third
15ce0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
15cf0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
15d00 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  ots.  The size o
15d10 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20  f the buffer in 
15d20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
15d30 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74  nt must be great
15d40 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71  er than.** or eq
15d50 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75  ual to the produ
15d60 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ct of the second
15d70 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d   and third argum
15d80 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65  ents.  The buffe
15d90 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69  r.** must be ali
15da0 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
15db0 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66  e boundary.  ^If
15dc0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
15dd0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54  ment to.** SQLIT
15de0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
15df0 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75  SIDE is not a mu
15e00 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20  ltiple of 8, it 
15e10 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  is internally.**
15e20 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f   rounded down to
15e30 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65   the next smalle
15e40 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e  r multiple of 8.
15e50 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64    ^(The lookasid
15e60 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66  e memory.** conf
15e70 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20  iguration for a 
15e80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15e90 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ion can only be 
15ea0 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61  changed when tha
15eb0 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  t.** connection 
15ec0 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
15ed0 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65   using lookaside
15ee0 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f   memory, or in o
15ef0 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68  ther words.** wh
15f00 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20  en the "current 
15f10 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20  value" returned 
15f20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64  by.** [sqlite3_d
15f30 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c  b_status](D,[SQL
15f40 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
15f50 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65  SIDE],...) is ze
15f60 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ro..** Any attem
15f70 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  pt to change the
15f80 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
15f90 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  y configuration 
15fa0 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a  when lookaside.*
15fb0 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75  * memory is in u
15fc0 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f  se leaves the co
15fd0 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68  nfiguration unch
15fe0 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e  anged and return
15ff0 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  s .** [SQLITE_BU
16000 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  SY].)^</dd>.**.*
16010 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
16020 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
16030 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  Y</dt>.** <dd> ^
16040 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
16050 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
16060 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66   disable the enf
16070 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b  orcement of.** [
16080 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73  foreign key cons
16090 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65  traints].  There
160a0 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
160b0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
160c0 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
160d0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
160e0 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
160f0 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46  s 0 to disable F
16100 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a  K enforcement,.*
16110 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
16120 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
16130 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ent or negative 
16140 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f  to leave FK enfo
16150 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61  rcement.** uncha
16160 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e  nged.  The secon
16170 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
16180 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
16190 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
161a0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
161b0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
161c0 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e  te whether FK en
161d0 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66  forcement is off
161e0 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77   or on.** follow
161f0 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
16200 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
16210 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
16220 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
16230 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
16240 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
16250 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
16260 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
16270 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
16280 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
16290 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74  ABLE_TRIGGER</dt
162a0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
162b0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
162c0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
162d0 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47  ble [CREATE TRIG
162e0 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e  GER | triggers].
162f0 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
16300 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
16310 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
16320 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
16330 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
16340 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
16350 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73  disable triggers
16360 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
16370 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73   enable triggers
16380 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
16390 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
163a0 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  g unchanged..** 
163b0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
163c0 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
163d0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
163e0 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
163f0 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
16400 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
16410 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65  her triggers are
16420 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
16430 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  bled.** followin
16440 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
16450 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
16460 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
16470 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
16480 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74  which case the t
16490 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69  rigger setting i
164a0 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
164b0 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
164c0 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
164d0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
164e0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20  G_LOOKASIDE     
164f0 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a    1001  /* void*
16500 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
16510 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
16520 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20  FIG_ENABLE_FKEY 
16530 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74      1002  /* int
16540 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
16550 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
16560 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20  _ENABLE_TRIGGER 
16570 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e   1003  /* int in
16580 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  t* */.../*.** CA
16590 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
165a0 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64  r Disable Extend
165b0 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  ed Result Codes.
165c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
165d0 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
165e0 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69  lt_codes() routi
165f0 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
16600 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65  sables the.** [e
16610 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
16620 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66  odes] feature of
16630 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78   SQLite. ^The ex
16640 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a  tended result.**
16650 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62   codes are disab
16660 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66  led by default f
16670 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f  or historical co
16680 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a  mpatibility..*/.
16690 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
166a0 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
166b0 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  s(sqlite3*, int 
166c0 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  onoff);../*.** C
166d0 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e  API3REF: Last In
166e0 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a  sert Rowid.**.**
166f0 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20   ^Each entry in 
16700 6d 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c  most SQLite tabl
16710 65 73 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b  es (except for [
16720 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74  WITHOUT ROWID] t
16730 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20  ables).** has a 
16740 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69  unique 64-bit si
16750 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  gned.** integer 
16760 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b  key called the [
16770 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d  ROWID | "rowid"]
16780 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20  . ^The rowid is 
16790 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65  always available
167a0 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c  .** as an undecl
167b0 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  ared column name
167c0 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72  d ROWID, OID, or
167d0 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67   _ROWID_ as long
167e0 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d   as those.** nam
167f0 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20  es are not also 
16800 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74  used by explicit
16810 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
16820 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20  mns. ^If.** the 
16830 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
16840 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45  mn of type [INTE
16850 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
16860 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d   then that colum
16870 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20  n.** is another 
16880 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f  alias for the ro
16890 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  wid..**.** ^The 
168a0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
168b0 65 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74  ert_rowid(D) int
168c0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
168d0 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
168e0 65 20 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e  e .** most recen
168f0 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  t successful [IN
16900 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77  SERT] into a row
16910 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72  id table or [vir
16920 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f  tual table].** o
16930 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  n database conne
16940 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73  ction D..** ^Ins
16950 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f  erts into [WITHO
16960 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73  UT ROWID] tables
16970 20 61 72 65 20 6e 6f 74 20 72 65 63 6f 72 64 65   are not recorde
16980 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63  d..** ^If no suc
16990 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
169a0 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62  s into rowid tab
169b0 6c 65 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72  les.** have ever
169c0 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 65   occurred on the
169d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
169e0 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68 65 6e  tion D, .** then
169f0 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
16a00 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65  sert_rowid(D) re
16a10 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
16a20 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52  * ^(If an [INSER
16a30 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  T] occurs within
16a40 20 61 20 74 72 69 67 67 65 72 20 6f 72 20 77 69   a trigger or wi
16a50 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20  thin a [virtual 
16a60 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64  table].** method
16a70 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  , then this rout
16a80 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ine will return 
16a90 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
16aa0 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72  he inserted.** r
16ab0 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ow as long as th
16ac0 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
16ad0 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f  tual table metho
16ae0 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  d is running..**
16af0 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72   But once the tr
16b00 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
16b10 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e   table method en
16b20 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  ds, the value re
16b30 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68  turned .** by th
16b40 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72  is routine rever
16b50 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 61  ts to what it wa
16b60 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69  s before the tri
16b70 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a  gger or virtual.
16b80 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20  ** table method 
16b90 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  began.)^.**.** ^
16ba0 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74  An [INSERT] that
16bb0 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20   fails due to a 
16bc0 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
16bd0 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a  tion is not a.**
16be0 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
16bf0 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f  ERT] and does no
16c00 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
16c10 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ue returned by t
16c20 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20  his.** routine. 
16c30 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52   ^Thus INSERT OR
16c40 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52   FAIL, INSERT OR
16c50 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20   IGNORE, INSERT 
16c60 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20  OR ROLLBACK,.** 
16c70 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42  and INSERT OR AB
16c80 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e  ORT make no chan
16c90 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72  ges to the retur
16ca0 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a  n value of this.
16cb0 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20  ** routine when 
16cc0 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20  their insertion 
16cd0 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49  fails.  ^(When I
16ce0 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
16cf0 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61  .** encounters a
16d00 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
16d10 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e  ation, it does n
16d20 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a  ot fail.  The.**
16d30 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65   INSERT continue
16d40 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  s to completion 
16d50 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72  after deleting r
16d60 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a  ows that caused.
16d70 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  ** the constrain
16d80 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53  t problem so INS
16d90 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77  ERT OR REPLACE w
16da0 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67  ill always chang
16db0 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20  e.** the return 
16dc0 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e  value of this in
16dd0 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a  terface.)^.**.**
16de0 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73   ^For the purpos
16df0 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  es of this routi
16e00 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20  ne, an [INSERT] 
16e10 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  is considered to
16e20 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75  .** be successfu
16e30 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  l even if it is 
16e40 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c  subsequently rol
16e50 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  led back..**.** 
16e60 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  This function is
16e70 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53   accessible to S
16e80 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69  QL statements vi
16e90 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69  a the.** [last_i
16ea0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51  nsert_rowid() SQ
16eb0 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
16ec0 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
16ed0 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73   thread performs
16ee0 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20   a new [INSERT] 
16ef0 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64  on the same.** d
16f00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16f10 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71  on while the [sq
16f20 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
16f30 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75  t_rowid()].** fu
16f40 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
16f50 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67  g and thus chang
16f60 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65  es the last inse
16f70 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74  rt [rowid],.** t
16f80 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
16f90 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
16fa0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
16fb0 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e  owid()] is.** un
16fc0 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
16fd0 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20  might not equal 
16fe0 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f  either the old o
16ff0 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73  r the new.** las
17000 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
17010 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
17020 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  64 sqlite3_last_
17030 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c  insert_rowid(sql
17040 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
17050 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54  API3REF: Count T
17060 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  he Number Of Row
17070 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a  s Modified.**.**
17080 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
17090 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
170a0 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 72  er of database r
170b0 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63 68  ows that were ch
170c0 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65  anged.** or inse
170d0 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20  rted or deleted 
170e0 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  by the most rece
170f0 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53  ntly completed S
17100 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL statement.** 
17110 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  on the [database
17120 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
17130 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69  cified by the fi
17140 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  rst parameter..*
17150 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65 73  * ^(Only changes
17160 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63 74   that are direct
17170 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ly specified by 
17180 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55  the [INSERT], [U
17190 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44  PDATE],.** or [D
171a0 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74  ELETE] statement
171b0 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41   are counted.  A
171c0 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73  uxiliary changes
171d0 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72   caused by.** tr
171e0 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 65 69  iggers or [forei
171f0 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20  gn key actions] 
17200 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
17210 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b 73  )^ Use the.** [s
17220 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
17230 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e  nges()] function
17240 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74   to find the tot
17250 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  al number of cha
17260 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e  nges.** includin
17270 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  g changes caused
17280 20 62 79 20 74 72 69 67 67 65 72 73 20 61 6e 64   by triggers and
17290 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74   foreign key act
172a0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61  ions..**.** ^Cha
172b0 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74  nges to a view t
172c0 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74 65  hat are simulate
172d0 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41 44  d by an [INSTEAD
172e0 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20   OF trigger].** 
172f0 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
17300 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c    Only real tabl
17310 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f  e changes are co
17320 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41  unted..**.** ^(A
17330 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73   "row change" is
17340 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73   a change to a s
17350 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73  ingle row of a s
17360 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63  ingle table.** c
17370 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45  aused by an INSE
17380 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55  RT, DELETE, or U
17390 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e  PDATE statement.
173a0 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61    Rows that.** a
173b0 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73 69  re changed as si
173c0 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b 52  de effects of [R
173d0 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
173e0 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a  nt resolution,.*
173f0 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52  * rollback, ABOR
17400 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44  T processing, [D
17410 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62  ROP TABLE], or b
17420 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d  y any other.** m
17430 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74  echanisms do not
17440 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74   count as direct
17450 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e 0a   row changes.)^.
17460 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72  **.** A "trigger
17470 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73   context" is a s
17480 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f  cope of executio
17490 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e  n that begins an
174a0 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74  d.** ends with t
174b0 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 5b  he script of a [
174c0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
174d0 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d   trigger]. .** M
174e0 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ost SQL statemen
174f0 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61  ts are.** evalua
17500 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61  ted outside of a
17510 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 69  ny trigger.  Thi
17520 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65  s is the "top le
17530 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20  vel".** trigger 
17540 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74  context.  If a t
17550 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72 6f  rigger fires fro
17560 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c  m the top level,
17570 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65   a.** new trigge
17580 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74  r context is ent
17590 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 72  ered for the dur
175a0 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e  ation of that on
175b0 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53  e.** trigger.  S
175c0 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61 74  ubtriggers creat
175d0 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f  e subcontexts fo
175e0 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e  r their duration
175f0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
17600 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
17610 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  ] or [sqlite3_st
17620 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c  ep()] recursivel
17630 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72  y does.** not cr
17640 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67  eate a new trigg
17650 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  er context..**.*
17660 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
17670 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
17680 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f  ber of direct ro
17690 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  w changes in the
176a0 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  .** most recent 
176b0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
176c0 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
176d0 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73  ent within the s
176e0 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63  ame.** trigger c
176f0 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ontext..**.** ^T
17700 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64  hus, when called
17710 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65   from the top le
17720 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69  vel, this functi
17730 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  on returns the.*
17740 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e  * number of chan
17750 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20  ges in the most 
17760 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55  recent INSERT, U
17770 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
17780 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63  .** that also oc
17790 63 75 72 72 65 64 20 61 74 20 74 68 65 20 74 6f  curred at the to
177a0 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74 68  p level.  ^(With
177b0 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61  in the body of a
177c0 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65   trigger,.** the
177d0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
177e0 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  () interface can
177f0 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69   be called to fi
17800 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
17810 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74  .** changes in t
17820 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
17830 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52   completed INSER
17840 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
17850 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  LETE.** statemen
17860 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64  t within the bod
17870 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72  y of the same tr
17880 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65  igger..** Howeve
17890 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65  r, the number re
178a0 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20  turned does not 
178b0 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a  include changes.
178c0 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75 62  ** caused by sub
178d0 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20 74  triggers since t
178e0 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 72 20  hose have their 
178f0 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a  own context.)^.*
17900 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
17910 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
17920 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
17930 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
17940 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
17950 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63  gma], and the [c
17960 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
17970 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
17980 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
17990 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
179a0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
179b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
179c0 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
179d0 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  e3_changes()] is
179e0 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
179f0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
17a00 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74  .** is unpredict
17a10 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
17a20 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  ningful..*/.int 
17a30 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
17a40 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
17a50 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61  * CAPI3REF: Tota
17a60 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  l Number Of Rows
17a70 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20   Modified.**.** 
17a80 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
17a90 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
17aa0 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73  r of row changes
17ab0 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53 45   caused by [INSE
17ac0 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d  RT],.** [UPDATE]
17ad0 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61   or [DELETE] sta
17ae0 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68  tements since th
17af0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
17b00 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e  ection] was open
17b10 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75  ed..** ^(The cou
17b20 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  nt returned by s
17b30 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
17b40 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65 73 20  nges() includes 
17b50 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66  all changes.** f
17b60 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45 20  rom all [CREATE 
17b70 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
17b80 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e 64 20  r] contexts and 
17b90 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79 0a  changes made by.
17ba0 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
17bb0 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65  actions]. Howeve
17bc0 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20  r,.** the count 
17bd0 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
17be0 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f   changes used to
17bf0 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c   implement [REPL
17c00 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73  ACE] constraints
17c10 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b  ,.** do rollback
17c20 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65  s or ABORT proce
17c30 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20  ssing, or [DROP 
17c40 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e  TABLE] processin
17c50 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74  g.  The.** count
17c60 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
17c70 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73 20  e rows of views 
17c80 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49 4e  that fire an [IN
17c90 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
17ca0 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66 20  ],.** though if 
17cb0 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20 74  the INSTEAD OF t
17cc0 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68 61  rigger makes cha
17cd0 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c  nges of its own,
17ce0 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20 0a   those changes .
17cf0 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 29  ** are counted.)
17d00 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ^.** ^The sqlite
17d10 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
17d20 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74  ) function count
17d30 73 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 73  s the changes as
17d40 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20   soon as.** the 
17d50 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d  statement that m
17d60 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d  akes them is com
17d70 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68 65  pleted (when the
17d80 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   statement handl
17d90 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 74  e.** is passed t
17da0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
17db0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
17dc0 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a  finalize()])..**
17dd0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
17de0 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
17df0 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
17e00 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
17e10 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
17e20 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68  nd the [total_ch
17e30 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
17e40 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
17e50 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
17e60 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
17e70 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
17e80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
17e90 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
17ea0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
17eb0 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
17ec0 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  en the value.** 
17ed0 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72  returned is unpr
17ee0 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
17ef0 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
17f00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74  .int sqlite3_tot
17f10 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  al_changes(sqlit
17f20 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
17f30 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74  I3REF: Interrupt
17f40 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20   A Long-Running 
17f50 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  Query.**.** ^Thi
17f60 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65  s function cause
17f70 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61  s any pending da
17f80 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
17f90 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a   to abort and.**
17fa0 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65   return at its e
17fb0 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e  arliest opportun
17fc0 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e  ity. This routin
17fd0 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a  e is typically.*
17fe0 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70  * called in resp
17ff0 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61  onse to a user a
18000 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72  ction such as pr
18010 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a  essing "Cancel".
18020 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65  ** or Ctrl-C whe
18030 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74  re the user want
18040 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f  s a long query o
18050 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74  peration to halt
18060 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  .** immediately.
18070 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61  .**.** ^It is sa
18080 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
18090 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74  routine from a t
180a0 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20  hread different 
180b0 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65  from the.** thre
180c0 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65  ad that is curre
180d0 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65  ntly running the
180e0 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
180f0 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20  ion.  But it.** 
18100 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63  is not safe to c
18110 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
18120 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
18130 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68  e connection] th
18140 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20  at.** is closed 
18150 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62  or might close b
18160 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e  efore sqlite3_in
18170 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e  terrupt() return
18180 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  s..**.** ^If an 
18190 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
181a0 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e   very nearly fin
181b0 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d  ished at the tim
181c0 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  e when.** sqlite
181d0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73  3_interrupt() is
181e0 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74   called, then it
181f0 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20   might not have 
18200 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a  an opportunity.*
18210 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70  * to be interrup
18220 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f  ted and might co
18230 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65  ntinue to comple
18240 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  tion..**.** ^An 
18250 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  SQL operation th
18260 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65  at is interrupte
18270 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  d will return [S
18280 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
18290 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74  ..** ^If the int
182a0 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65  errupted SQL ope
182b0 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53  ration is an INS
182c0 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
182d0 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69  DELETE.** that i
182e0 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c  s inside an expl
182f0 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
18300 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72  , then the entir
18310 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a  e transaction.**
18320 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20   will be rolled 
18330 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c  back automatical
18340 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
18350 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
18360 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65  (D) call is in e
18370 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20  ffect until all 
18380 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
18390 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  g.** SQL stateme
183a0 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  nts on [database
183b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63   connection] D c
183c0 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e  omplete.  ^Any n
183d0 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ew SQL statement
183e0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
183f0 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
18400 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
18410 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66  t() call and bef
18420 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e  ore the .** runn
18430 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72  ing statements r
18440 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20  eaches zero are 
18450 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69  interrupted as i
18460 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a  f they had been.
18470 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72  ** running prior
18480 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
18490 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
184a0 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74  .  ^New SQL stat
184b0 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
184c0 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
184d0 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61   the running sta
184e0 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61  tement count rea
184f0 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a  ches zero are.**
18500 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79   not effected by
18510 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
18520 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20  errupt()..** ^A 
18530 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
18540 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61  interrupt(D) tha
18550 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68  t occurs when th
18560 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69  ere are no runni
18570 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
18580 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20  ents is a no-op 
18590 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63  and has no effec
185a0 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t on SQL stateme
185b0 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
185c0 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
185d0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
185e0 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72  upt() call retur
185f0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ns..**.** If the
18600 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
18610 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c  tion closes whil
18620 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  e [sqlite3_inter
18630 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75  rupt()].** is ru
18640 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74  nning then bad t
18650 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c  hings will likel
18660 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69  y happen..*/.voi
18670 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  d sqlite3_interr
18680 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  upt(sqlite3*);..
18690 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
186a0 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
186b0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73  SQL Statement Is
186c0 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20   Complete.**.** 
186d0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
186e0 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67  re useful during
186f0 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e   command-line in
18700 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  put to determine
18710 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65   if the.** curre
18720 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78  ntly entered tex
18730 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20  t seems to form 
18740 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
18750 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69  tatement or.** i
18760 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70  f additional inp
18770 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66  ut is needed bef
18780 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20  ore sending the 
18790 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c  text into.** SQL
187a0 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e  ite for parsing.
187b0 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65    ^These routine
187c0 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68  s return 1 if th
187d0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a  e input string.*
187e0 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20  * appears to be 
187f0 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
18800 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74  tatement.  ^A st
18810 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65  atement is judge
18820 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c  d to be.** compl
18830 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77  ete if it ends w
18840 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20  ith a semicolon 
18850 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74  token and is not
18860 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a   a prefix of a.*
18870 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52  * well-formed CR
18880 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61  EATE TRIGGER sta
18890 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f  tement.  ^Semico
188a0 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d  lons that are em
188b0 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a  bedded within.**
188c0 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73   string literals
188d0 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74   or quoted ident
188e0 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63  ifier names or c
188f0 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a  omments are not.
18900 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74  ** independent t
18910 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20  okens (they are 
18920 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65  part of the toke
18930 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20  n in which they 
18940 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29  are.** embedded)
18950 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74   and thus do not
18960 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74   count as a stat
18970 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72  ement terminator
18980 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a  .  ^Whitespace.*
18990 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74  * and comments t
189a0 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66  hat follow the f
189b0 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61  inal semicolon a
189c0 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  re ignored..**.*
189d0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
189e0 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 68  s return 0 if th
189f0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69  e statement is i
18a00 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20  ncomplete.  ^If 
18a10 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  a.** memory allo
18a20 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68  cation fails, th
18a30 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  en SQLITE_NOMEM 
18a40 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
18a50 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
18a60 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20  es do not parse 
18a70 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
18a80 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20  ts thus.** will 
18a90 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61  not detect synta
18aa0 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65  ctically incorre
18ab0 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ct SQL..**.** ^(
18ac0 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f  If SQLite has no
18ad0 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a  t been initializ
18ae0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
18af0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
18b00 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76  prior .** to inv
18b10 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f  oking sqlite3_co
18b20 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20  mplete16() then 
18b30 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
18b40 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
18b50 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
18b60 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70   by sqlite3_comp
18b70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68  lete16().  If th
18b80 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  at initializatio
18b90 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e  n fails,.** then
18ba0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
18bb0 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
18bc0 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c  omplete16() will
18bd0 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20   be non-zero.** 
18be0 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
18bf0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
18c00 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f   input SQL is co
18c10 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  mplete.)^.**.** 
18c20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  The input to [sq
18c30 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29  lite3_complete()
18c40 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ] must be a zero
18c50 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
18c60 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  TF-8 string..**.
18c70 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
18c80 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
18c90 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61  e16()] must be a
18ca0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
18cb0 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
18cc0 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  g in native byte
18cd0 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73   order..*/.int s
18ce0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
18cf0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29  const char *sql)
18d00 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
18d10 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76  mplete16(const v
18d20 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a  oid *sql);../*.*
18d30 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69  * CAPI3REF: Regi
18d40 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20  ster A Callback 
18d50 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45  To Handle SQLITE
18d60 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a  _BUSY Errors.**.
18d70 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
18d80 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58  busy_handler(D,X
18d90 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73  ,P) routine sets
18da0 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
18db0 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d  tion X.** that m
18dc0 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
18dd0 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20  with argument P 
18de0 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61  whenever.** an a
18df0 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74  ttempt is made t
18e00 6f 20 61 63 63 65 73 73 20 61 20 64 61 74 61 62  o access a datab
18e10 61 73 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69  ase table associ
18e20 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61  ated with.** [da
18e30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18e40 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65  n] D when anothe
18e50 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70  r thread.** or p
18e60 72 6f 63 65 73 73 20 68 61 73 20 74 68 65 20 74  rocess has the t
18e70 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20  able locked..** 
18e80 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79  The sqlite3_busy
18e90 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72  _handler() inter
18ea0 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
18eb0 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71  implement.** [sq
18ec0 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
18ed0 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d  ut()] and [PRAGM
18ee0 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e  A busy_timeout].
18ef0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62  .**.** ^If the b
18f00 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
18f10 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49  NULL, then [SQLI
18f20 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72  TE_BUSY].** is r
18f30 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
18f40 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74  ely upon encount
18f50 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20  ering the lock. 
18f60 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
18f70 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74  llback.** is not
18f80 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
18f90 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62  callback might b
18fa0 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
18fb0 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  wo arguments..**
18fc0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
18fd0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62  rgument to the b
18fe0 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61  usy handler is a
18ff0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
19000 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  d* pointer which
19010 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64  .** is the third
19020 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
19030 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
19040 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  r().  ^The secon
19050 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
19060 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
19070 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
19080 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65  e number of time
19090 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20  s that the busy 
190a0 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62  handler has.** b
190b0 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20  een invoked for 
190c0 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67  the same locking
190d0 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
190e0 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63  .** busy callbac
190f0 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65  k returns 0, the
19100 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20  n no additional 
19110 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64  attempts are mad
19120 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74  e to.** access t
19130 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
19140 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73  [SQLITE_BUSY] is
19150 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20   returned.** to 
19160 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
19170 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c  .** ^If the call
19180 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
19190 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74  -zero, then anot
191a0 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69  her attempt.** i
191b0 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73  s made to access
191c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
191d0 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65  d the cycle repe
191e0 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ats..**.** The p
191f0 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73  resence of a bus
19200 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e  y handler does n
19210 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  ot guarantee tha
19220 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76  t it will be inv
19230 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  oked.** when the
19240 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65  re is lock conte
19250 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74  ntion. ^If SQLit
19260 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61  e determines tha
19270 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  t invoking the b
19280 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63  usy.** handler c
19290 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
192a0 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69   deadlock, it wi
192b0 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20  ll go ahead and 
192c0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42  return [SQLITE_B
192d0 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61  USY].** to the a
192e0 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65  pplication inste
192f0 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74  ad of invoking t
19300 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64  he .** busy hand
19310 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72  ler..** Consider
19320 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72   a scenario wher
19330 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73  e one process is
19340 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20   holding a read 
19350 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20  lock that.** it 
19360 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f  is trying to pro
19370 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76  mote to a reserv
19380 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61  ed lock and.** a
19390 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
193a0 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73  is holding a res
193b0 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20  erved lock that 
193c0 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20  it is trying.** 
193d0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e  to promote to an
193e0 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e   exclusive lock.
193f0 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63    The first proc
19400 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65  ess cannot proce
19410 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74  ed.** because it
19420 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
19430 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
19440 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
19450 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65   cannot.** proce
19460 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ed because it is
19470 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
19480 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20  first.  If both 
19490 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76  processes.** inv
194a0 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e  oke the busy han
194b0 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77  dlers, neither w
194c0 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f  ill make any pro
194d0 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72  gress.  Therefor
194e0 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74  e,.** SQLite ret
194f0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53  urns [SQLITE_BUS
19500 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  Y] for the first
19510 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67   process, hoping
19520 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69   that this.** wi
19530 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69  ll induce the fi
19540 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72  rst process to r
19550 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20  elease its read 
19560 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a  lock and allow.*
19570 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  * the second pro
19580 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e  cess to proceed.
19590 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
195a0 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63  ult busy callbac
195b0 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  k is NULL..**.**
195c0 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
195d0 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
195e0 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e  sy handler defin
195f0 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b  ed for each.** [
19600 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19610 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61  ion].  Setting a
19620 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65   new busy handle
19630 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20  r clears any.** 
19640 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68  previously set h
19650 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65  andler.)^  ^Note
19660 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73   that calling [s
19670 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
19680 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61  out()].** or eva
19690 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20  luating [PRAGMA 
196a0 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20  busy_timeout=N] 
196b0 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a  will change the.
196c0 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ** busy handler 
196d0 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20 61  and thus clear a
196e0 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ny previously se
196f0 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  t busy handler..
19700 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63  **.** The busy c
19710 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e  allback should n
19720 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69  ot take any acti
19730 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79  ons which modify
19740 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
19750 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
19760 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
19770 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f  y handler.  In o
19780 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74  ther words,.** t
19790 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
197a0 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  is not reentrant
197b0 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69  .  Any such acti
197c0 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e  ons.** result in
197d0 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
197e0 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75  ior..** .** A bu
197f0 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20  sy handler must 
19800 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61  not close the da
19810 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19820 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65  n.** or [prepare
19830 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
19840 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
19850 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69  sy handler..*/.i
19860 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
19870 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
19880 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69  , int(*)(void*,i
19890 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  nt), void*);../*
198a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
198b0 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74  t A Busy Timeout
198c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
198d0 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c  tine sets a [sql
198e0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
198f0 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  r | busy handler
19900 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a  ] that sleeps.**
19910 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64   for a specified
19920 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20   amount of time 
19930 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20  when a table is 
19940 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61  locked.  ^The ha
19950 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c  ndler.** will sl
19960 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  eep multiple tim
19970 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73  es until at leas
19980 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
19990 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a  nds of sleeping.
199a0 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61  ** have accumula
199b0 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20  ted.  ^After at 
199c0 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
199d0 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
199e0 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64  ing,.** the hand
199f0 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68  ler returns 0 wh
19a00 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69  ich causes [sqli
19a10 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72  te3_step()] to r
19a20 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
19a30 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43  _BUSY]..**.** ^C
19a40 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
19a50 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75  ine with an argu
19a60 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f  ment less than o
19a70 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a  r equal to zero.
19a80 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c  ** turns off all
19a90 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a   busy handlers..
19aa0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
19ab0 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
19ac0 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
19ad0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
19ae0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
19af0 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79  nnection] at any
19b00 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20   given moment.  
19b10 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20  If another busy 
19b20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64  handler.** was d
19b30 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b  efined  (using [
19b40 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
19b50 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74  dler()]) prior t
19b60 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69  o calling.** thi
19b70 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20  s routine, that 
19b80 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
19b90 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e  er is cleared.)^
19ba0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
19bb0 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74    [PRAGMA busy_t
19bc0 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73  imeout].*/.int s
19bd0 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
19be0 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  out(sqlite3*, in
19bf0 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t ms);../*.** CA
19c00 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65  PI3REF: Convenie
19c10 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72  nce Routines For
19c20 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73   Running Queries
19c30 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  .**.** This is a
19c40 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
19c50 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72  e that is preser
19c60 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ved for backward
19c70 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
19c80 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20  .** Use of this 
19c90 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
19ca0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a   recommended..**
19cb0 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20  .** Definition: 
19cc0 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c  A <b>result tabl
19cd0 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20  e</b> is memory 
19ce0 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63  data structure c
19cf0 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a  reated by the.**
19d00 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
19d10 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ble()] interface
19d20 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  .  A result tabl
19d30 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a  e records the.**
19d40 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20   complete query 
19d50 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65  results from one
19d60 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73   or more queries
19d70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ..**.** The tabl
19d80 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68  e conceptually h
19d90 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72  as a number of r
19da0 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e  ows and columns.
19db0 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e    But.** these n
19dc0 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70  umbers are not p
19dd0 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c  art of the resul
19de0 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20  t table itself. 
19df0 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72   These.** number
19e00 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73  s are obtained s
19e10 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20  eparately.  Let 
19e20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  N be the number 
19e30 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d  of rows.** and M
19e40 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
19e50 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a  f columns..**.**
19e60 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
19e70 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
19e80 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d  ointers to zero-
19e90 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
19ea0 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65   strings..** The
19eb0 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65  re are (N+1)*M e
19ec0 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61  lements in the a
19ed0 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74  rray.  The first
19ee0 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e   M pointers poin
19ef0 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72  t.** to zero-ter
19f00 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
19f10 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68  that  contain th
19f20 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63  e names of the c
19f30 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72  olumns..** The r
19f40 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73  emaining entries
19f50 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75   all point to qu
19f60 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55  ery results.  NU
19f70 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74  LL values result
19f80 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e  .** in NULL poin
19f90 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72  ters.  All other
19fa0 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74   values are in t
19fb0 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d  heir UTF-8 zero-
19fc0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
19fd0 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74  ring representat
19fe0 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20  ion as returned 
19ff0 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
1a000 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a  mn_text()]..**.*
1a010 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
1a020 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f   might consist o
1a030 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65  f one or more me
1a040 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
1a050 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  ..** It is not s
1a060 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65  afe to pass a re
1a070 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63  sult table direc
1a080 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  tly to [sqlite3_
1a090 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65  free()]..** A re
1a0a0 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c  sult table shoul
1a0b0 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  d be deallocated
1a0c0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1a0d0 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a  free_table()]..*
1a0e0 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61  *.** ^(As an exa
1a0f0 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75  mple of the resu
1a100 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c  lt table format,
1a110 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79   suppose a query
1a120 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73   result.** is as
1a130 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1a140 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1a150 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65  >.**        Name
1a160 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a          | Age.**
1a170 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d          --------
1a180 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
1a190 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20  **        Alice 
1a1a0 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20        | 43.**   
1a1b0 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20       Bob        
1a1c0 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20   | 28.**        
1a1d0 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31  Cindy       | 21
1a1e0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1a1f0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1a200 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75  ere are two colu
1a210 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68  mn (M==2) and th
1a220 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e  ree rows (N==3).
1a230 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65    Thus the.** re
1a240 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38  sult table has 8
1a250 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f   entries.  Suppo
1a260 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  se the result ta
1a270 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a  ble is stored.**
1a280 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d   in an array nam
1a290 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68  es azResult.  Th
1a2a0 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64  en azResult hold
1a2b0 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a  s this content:.
1a2c0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1a2d0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
1a2e0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30    azResult&#91;0
1a2f0 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20  ] = "Name";.**  
1a300 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1a310 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a  91;1] = "Age";.*
1a320 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1a330 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63  t&#91;2] = "Alic
1a340 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1a350 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20  Result&#91;3] = 
1a360 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "43";.**        
1a370 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20  azResult&#91;4] 
1a380 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20  = "Bob";.**     
1a390 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1a3a0 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20  5] = "28";.**   
1a3b0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1a3c0 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a  1;6] = "Cindy";.
1a3d0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1a3e0 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22  lt&#91;7] = "21"
1a3f0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1a400 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
1a410 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
1a420 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69  t_table() functi
1a430 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65  on evaluates one
1a440 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69   or more.** semi
1a450 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20  colon-separated 
1a460 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
1a470 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  n the zero-termi
1a480 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73  nated UTF-8.** s
1a490 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64  tring of its 2nd
1a4a0 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
1a4b0 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20  eturns a result 
1a4c0 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20  table to the.** 
1a4d0 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e  pointer given in
1a4e0 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74   its 3rd paramet
1a4f0 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  er..**.** After 
1a500 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1a510 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
1a520 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  h the result fro
1a530 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  m sqlite3_get_ta
1a540 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73  ble(),.** it mus
1a550 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c  t pass the resul
1a560 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20  t table pointer 
1a570 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  to sqlite3_free_
1a580 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72  table() in order
1a590 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74   to.** release t
1a5a0 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77  he memory that w
1a5b0 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65  as malloced.  Be
1a5c0 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79  cause of the way
1a5d0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1a5e0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65  _malloc()] happe
1a5f0 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65  ns within sqlite
1a600 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74  3_get_table(), t
1a610 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75  he calling.** fu
1a620 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  nction must not 
1a630 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c  try to call [sql
1a640 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72  ite3_free()] dir
1a650 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20  ectly.  Only.** 
1a660 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
1a670 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74  ble()] is able t
1a680 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  o release the me
1a690 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e  mory properly an
1a6a0 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  d safely..**.** 
1a6b0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1a6c0 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  table() interfac
1a6d0 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
1a6e0 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72   as a wrapper ar
1a6f0 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
1a700 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73  _exec()].  The s
1a710 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1a720 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
1a730 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a  not have access.
1a740 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e  ** to any intern
1a750 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72  al data structur
1a760 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49  es of SQLite.  I
1a770 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20  t uses only the 
1a780 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66  public.** interf
1a790 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65  ace defined here
1a7a0 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65  .  As a conseque
1a7b0 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74  nce, errors that
1a7c0 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a   occur in the.**
1a7d0 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f   wrapper layer o
1a7e0 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e  utside of the in
1a7f0 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f  ternal [sqlite3_
1a800 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65  exec()] call are
1a810 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65   not.** reflecte
1a820 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  d in subsequent 
1a830 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
1a840 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a  3_errcode()] or.
1a850 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
1a860 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  sg()]..*/.int sq
1a870 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1a880 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1a890 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f           /* An o
1a8a0 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  pen database */.
1a8b0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
1a8c0 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74  ql,     /* SQL t
1a8d0 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
1a8e0 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52  /.  char ***pazR
1a8f0 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73  esult,    /* Res
1a900 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72  ults of the quer
1a910 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f  y */.  int *pnRo
1a920 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  w,           /* 
1a930 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
1a940 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65   rows written he
1a950 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43  re */.  int *pnC
1a960 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a  olumn,        /*
1a970 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
1a980 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65  t columns writte
1a990 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72  n here */.  char
1a9a0 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20   **pzErrmsg     
1a9b0 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
1a9c0 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
1a9d0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
1a9e0 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a  ree_table(char *
1a9f0 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a  *result);../*.**
1aa00 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61   CAPI3REF: Forma
1aa10 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e  tted String Prin
1aa20 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ting Functions.*
1aa30 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1aa40 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69  nes are work-ali
1aa50 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e  kes of the "prin
1aa60 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20  tf()" family of 
1aa70 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f  functions.** fro
1aa80 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
1aa90 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20   library..**.** 
1aaa0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72  ^The sqlite3_mpr
1aab0 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
1aac0 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f  e3_vmprintf() ro
1aad0 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65  utines write the
1aae0 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ir.** results in
1aaf0 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
1ab00 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
1ab10 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54  _malloc()]..** T
1ab20 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
1ab30 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
1ab40 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
1ab50 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
1ab60 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
1ab70 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74  ()].  ^Both rout
1ab80 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a  ines return a.**
1ab90 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
1aba0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1abb0 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ()] is unable to
1abc0 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68   allocate enough
1abd0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** memory to ho
1abe0 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  ld the resulting
1abf0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e   string..**.** ^
1ac00 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70  (The sqlite3_snp
1ac10 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
1ac20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73  is similar to "s
1ac30 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a  nprintf()" from.
1ac40 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  ** the standard 
1ac50 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  C library.  The 
1ac60 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65  result is writte
1ac70 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75  n into the.** bu
1ac80 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73  ffer supplied as
1ac90 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1aca0 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65  meter whose size
1acb0 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20   is given by.** 
1acc0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
1acd0 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74  ter. Note that t
1ace0 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a  he order of the.
1acf0 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72  ** first two par
1ad00 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72  ameters is rever
1ad10 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74  sed from snprint
1ad20 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20  f().)^  This is 
1ad30 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c  an.** historical
1ad40 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63   accident that c
1ad50 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77  annot be fixed w
1ad60 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a  ithout breaking.
1ad70 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
1ad80 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e  patibility.  ^(N
1ad90 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71  ote also that sq
1ada0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1adb0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f  .** returns a po
1adc0 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66  inter to its buf
1add0 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74  fer instead of t
1ade0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
1adf0 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61  characters actua
1ae00 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  lly written into
1ae10 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20   the buffer.)^  
1ae20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a  We admit that.**
1ae30 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1ae40 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65  haracters writte
1ae50 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72  n would be a mor
1ae60 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a  e useful return.
1ae70 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20  ** value but we 
1ae80 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  cannot change th
1ae90 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
1aea0 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
1aeb0 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69  intf().** now wi
1aec0 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63  thout breaking c
1aed0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
1aee0 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20  .** ^As long as 
1aef0 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20  the buffer size 
1af00 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  is greater than 
1af10 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e  zero, sqlite3_sn
1af20 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72  printf().** guar
1af30 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
1af40 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73  buffer is always
1af50 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1af60 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a  .  ^The first.**
1af70 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69   parameter "n" i
1af80 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65  s the total size
1af90 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20   of the buffer, 
1afa0 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20  including space 
1afb0 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20  for.** the zero 
1afc0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20  terminator.  So 
1afd0 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69  the longest stri
1afe0 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63  ng that can be c
1aff0 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69  ompletely.** wri
1b000 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31  tten will be n-1
1b010 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
1b020 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1b030 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  vsnprintf() rout
1b040 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73  ine is a varargs
1b050 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69   version of sqli
1b060 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a  te3_snprintf()..
1b070 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1b080 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  ines all impleme
1b090 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  nt some addition
1b0a0 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a  al formatting.**
1b0b0 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72   options that ar
1b0c0 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e  e useful for con
1b0d0 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74  structing SQL st
1b0e0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c  atements..** All
1b0f0 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72   of the usual pr
1b100 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e  intf() formattin
1b110 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e  g options apply.
1b120 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74    In addition, t
1b130 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22  here.** is are "
1b140 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22  %q", "%Q", and "
1b150 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a  %z" options..**.
1b160 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69  ** ^(The %q opti
1b170 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73  on works like %s
1b180 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73   in that it subs
1b190 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65  titutes a nul-te
1b1a0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
1b1b0 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75  ng from the argu
1b1c0 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20  ment list.  But 
1b1d0 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20  %q also doubles 
1b1e0 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61  every '\'' chara
1b1f0 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64  cter..** %q is d
1b200 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20  esigned for use 
1b210 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20  inside a string 
1b220 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64  literal.)^  By d
1b230 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27  oubling each '\'
1b240 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69  '.** character i
1b250 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63  t escapes that c
1b260 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c  haracter and all
1b270 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73  ows it to be ins
1b280 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  erted into.** th
1b290 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  e string..**.** 
1b2a0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73  For example, ass
1b2b0 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76  ume the string v
1b2c0 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f  ariable zText co
1b2d0 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66  ntains text as f
1b2e0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1b2f0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1b300 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20  **  char *zText 
1b310 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20  = "It's a happy 
1b320 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  day!";.** </pre>
1b330 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1b340 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20  .** One can use 
1b350 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20  this text in an 
1b360 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
1b370 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1b380 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1b390 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
1b3a0 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
1b3b0 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
1b3c0 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71  table VALUES('%q
1b3d0 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  ')", zText);.** 
1b3e0 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
1b3f0 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
1b400 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
1b410 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
1b420 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1b430 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
1b440 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72  he %q format str
1b450 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
1b460 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20   '\'' character 
1b470 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65  in zText.** is e
1b480 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53  scaped and the S
1b490 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20  QL generated is 
1b4a0 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1b4b0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1b4c0 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
1b4d0 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
1b4e0 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79  S('It''s a happy
1b4f0 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65   day!').** </pre
1b500 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1b510 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72  *.** This is cor
1b520 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73  rect.  Had we us
1b530 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66  ed %s instead of
1b540 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74   %q, the generat
1b550 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20  ed SQL.** would 
1b560 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65  have looked like
1b570 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c   this:.**.** <bl
1b580 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1b590 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
1b5a0 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
1b5b0 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
1b5c0 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1b5d0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1b5e0 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d  This second exam
1b5f0 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79  ple is an SQL sy
1b600 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20  ntax error.  As 
1b610 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79  a general rule y
1b620 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77  ou should.** alw
1b630 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65  ays use %q inste
1b640 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e  ad of %s when in
1b650 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74  serting text int
1b660 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  o a string liter
1b670 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  al..**.** ^(The 
1b680 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %Q option works 
1b690 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69  like %q except i
1b6a0 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67  t also adds sing
1b6b0 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64  le quotes around
1b6c0 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20  .** the outside 
1b6d0 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72  of the total str
1b6e0 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ing.  Additional
1b6f0 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d  ly, if the param
1b700 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61  eter in the.** a
1b710 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20  rgument list is 
1b720 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
1b730 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74  %Q substitutes t
1b740 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28  he text "NULL" (
1b750 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c  without.** singl
1b760 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f  e quotes).)^  So
1b770 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f  , for example, o
1b780 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a  ne could say:.**
1b790 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1b7a0 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
1b7b0 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
1b7c0 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
1b7d0 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
1b7e0 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  (%Q)", zText);.*
1b7f0 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
1b800 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
1b810 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
1b820 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
1b830 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1b840 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  e>.**.** The cod
1b850 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e  e above will ren
1b860 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51  der a correct SQ
1b870 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  L statement in t
1b880 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61  he zSQL.** varia
1b890 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20  ble even if the 
1b8a0 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69  zText variable i
1b8b0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1b8c0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25  ..**.** ^(The "%
1b8d0 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  z" formatting op
1b8e0 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1b8f0 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68  "%s" but with th
1b900 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68  e.** addition th
1b910 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72  at after the str
1b920 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61  ing has been rea
1b930 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74  d and copied int
1b940 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c  o.** the result,
1b950 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1b960 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74  ] is called on t
1b970 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e  he input string.
1b980 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69  )^.*/.char *sqli
1b990 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73  te3_mprintf(cons
1b9a0 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68  t char*,...);.ch
1b9b0 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72  ar *sqlite3_vmpr
1b9c0 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
1b9d0 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72  , va_list);.char
1b9e0 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   *sqlite3_snprin
1b9f0 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e  tf(int,char*,con
1ba00 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a  st char*, ...);.
1ba10 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73  char *sqlite3_vs
1ba20 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1ba30 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  *,const char*, v
1ba40 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  a_list);../*.** 
1ba50 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
1ba60 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73   Allocation Subs
1ba70 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ystem.**.** The 
1ba80 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
1ba90 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75   these three rou
1baa0 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66  tines for all of
1bab0 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65   its own.** inte
1bac0 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rnal memory allo
1bad0 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43  cation needs. "C
1bae0 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76  ore" in the prev
1baf0 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a  ious sentence.**
1bb00 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
1bb10 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  e operating-syst
1bb20 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20  em specific VFS 
1bb30 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
1bb40 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20   The.** Windows 
1bb50 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20  VFS uses native 
1bb60 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
1bb70 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65  e() for some ope
1bb80 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  rations..**.** ^
1bb90 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  The sqlite3_mall
1bba0 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  oc() routine ret
1bbb0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1bbc0 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20  o a block.** of 
1bbd0 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20  memory at least 
1bbe0 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74  N bytes in lengt
1bbf0 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  h, where N is th
1bc00 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
1bc10 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
1bc20 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  oc() is unable t
1bc30 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69  o obtain suffici
1bc40 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f  ent free.** memo
1bc50 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61  ry, it returns a
1bc60 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
1bc70 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65  ^If the paramete
1bc80 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  r N to.** sqlite
1bc90 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  3_malloc() is ze
1bca0 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  ro or negative t
1bcb0 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  hen sqlite3_mall
1bcc0 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  oc() returns.** 
1bcd0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1bce0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1bcf0 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72  e3_malloc64(N) r
1bd00 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73  outine works jus
1bd10 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  t like.** sqlite
1bd20 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65  3_malloc(N) exce
1bd30 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20  pt that N is an 
1bd40 75 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20  unsigned 64-bit 
1bd50 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a  integer instead.
1bd60 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33  ** of a signed 3
1bd70 32 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a  2-bit integer..*
1bd80 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71  *.** ^Calling sq
1bd90 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74  lite3_free() wit
1bda0 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76  h a pointer prev
1bdb0 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a  iously returned.
1bdc0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ** by sqlite3_ma
1bdd0 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
1bde0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65  3_realloc() rele
1bdf0 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79  ases that memory
1be00 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d   so.** that it m
1be10 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20  ight be reused. 
1be20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72   ^The sqlite3_fr
1be30 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a  ee() routine is.
1be40 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73  ** a no-op if is
1be50 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
1be60 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61  ULL pointer.  Pa
1be70 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69  ssing a NULL poi
1be80 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  nter.** to sqlit
1be90 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72  e3_free() is har
1bea0 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65  mless.  After be
1beb0 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72  ing freed, memor
1bec0 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74  y.** should neit
1bed0 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20  her be read nor 
1bee0 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72  written.  Even r
1bef0 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c  eading previousl
1bf00 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72  y freed.** memor
1bf10 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  y might result i
1bf20 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  n a segmentation
1bf30 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20   fault or other 
1bf40 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a  severe error..**
1bf50 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69   Memory corrupti
1bf60 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69  on, a segmentati
1bf70 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68  on fault, or oth
1bf80 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a  er severe error.
1bf90 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ** might result 
1bfa0 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  if sqlite3_free(
1bfb0 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
1bfc0 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
1bfd0 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20  ter that.** was 
1bfe0 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  not obtained fro
1bff0 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
1c000 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
1c010 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  alloc()..**.** ^
1c020 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  The sqlite3_real
1c030 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61  loc(X,N) interfa
1c040 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  ce attempts to r
1c050 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72  esize a.** prior
1c060 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1c070 6f 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65  on X to be at le
1c080 61 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20  ast N bytes..** 
1c090 5e 49 66 20 74 68 65 20 58 20 70 61 72 61 6d 65  ^If the X parame
1c0a0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1c0b0 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69  ealloc(X,N).** i
1c0c0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1c0d0 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69   then its behavi
1c0e0 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20  or is identical 
1c0f0 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  to calling.** sq
1c100 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e  lite3_malloc(N).
1c110 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61  .** ^If the N pa
1c120 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1c130 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1c140 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65  is zero or.** ne
1c150 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20  gative then the 
1c160 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63  behavior is exac
1c170 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20  tly the same as 
1c180 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
1c190 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e  e3_free(X)..** ^
1c1a0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1c1b0 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70  X,N) returns a p
1c1c0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
1c1d0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
1c1e0 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
1c1f0 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20  ytes in size or 
1c200 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63  NULL if insuffic
1c210 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61  ient memory is a
1c220 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66  vailable..** ^If
1c230 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f   M is the size o
1c240 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
1c250 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e  cation, then min
1c260 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f  (N,M) bytes.** o
1c270 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
1c280 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65  cation are copie
1c290 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e  d into the begin
1c2a0 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72  ning of buffer r
1c2b0 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
1c2c0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1c2d0 4e 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72  N) and the prior
1c2e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66   allocation is f
1c2f0 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  reed..** ^If sql
1c300 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1c310 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61  ) returns NULL a
1c320 6e 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65  nd N is positive
1c330 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72  , then the.** pr
1c340 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
1c350 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a  s not freed..**.
1c360 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1c370 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69  realloc64(X,N) i
1c380 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20  nterfaces works 
1c390 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73  the same as.** s
1c3a0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1c3b0 2c 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20  ,N) except that 
1c3c0 4e 20 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e  N is a 64-bit un
1c3d0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69  signed integer i
1c3e0 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33  nstead.** of a 3
1c3f0 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  2-bit signed int
1c400 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  eger..**.** ^If 
1c410 58 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c  X is a memory al
1c420 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75  location previou
1c430 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
1c440 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
1c450 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  (),.** sqlite3_m
1c460 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74  alloc64(), sqlit
1c470 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72  e3_realloc(), or
1c480 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1c490 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  64(), then.** sq
1c4a0 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72  lite3_msize(X) r
1c4b0 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20  eturns the size 
1c4c0 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61  of that memory a
1c4d0 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74  llocation in byt
1c4e0 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75  es..** ^The valu
1c4f0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
1c500 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d  lite3_msize(X) m
1c510 69 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 74  ight be larger t
1c520 68 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a  han the number.*
1c530 2a 20 6f 66 20 62 79 74 65 73 20 72 65 71 75 65  * of bytes reque
1c540 73 74 65 64 20 77 68 65 6e 20 58 20 77 61 73 20  sted when X was 
1c550 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20  allocated.  ^If 
1c560 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  X is a NULL poin
1c570 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  ter then.** sqli
1c580 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74  te3_msize(X) ret
1c590 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58  urns zero.  If X
1c5a0 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74   points to somet
1c5b0 68 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74  hing that is not
1c5c0 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  .** the beginnin
1c5d0 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  g of memory allo
1c5e0 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74  cation, or if it
1c5f0 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72   points to a for
1c600 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d  merly.** valid m
1c610 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1c620 20 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65   that has now be
1c630 65 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74  en freed, then t
1c640 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
1c650 66 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  f sqlite3_msize(
1c660 58 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  X) is undefined 
1c670 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72  and possibly har
1c680 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mful..**.** ^The
1c690 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64   memory returned
1c6a0 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
1c6b0 6f 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65  oc(), sqlite3_re
1c6c0 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69  alloc(),.** sqli
1c6d0 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20  te3_malloc64(), 
1c6e0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  and sqlite3_real
1c6f0 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c  loc64().** is al
1c700 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20  ways aligned to 
1c710 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79  at least an 8 by
1c720 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20  te boundary, or 
1c730 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62  to a.** 4 byte b
1c740 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b  oundary if the [
1c750 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c  SQLITE_4_BYTE_AL
1c760 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f  IGNED_MALLOC] co
1c770 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
1c780 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a  tion is used..**
1c790 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65  .** In SQLite ve
1c7a0 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20  rsion 3.5.0 and 
1c7b0 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f  3.5.1, it was po
1c7c0 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65  ssible to define
1c7d0 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  .** the SQLITE_O
1c7e0 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43  MIT_MEMORY_ALLOC
1c7f0 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c  ATION which woul
1c800 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c  d cause the buil
1c810 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  t-in.** implemen
1c820 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20  tation of these 
1c830 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f  routines to be o
1c840 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61  mitted.  That ca
1c850 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e  pability.** is n
1c860 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65  o longer provide
1c870 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69  d.  Only built-i
1c880 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
1c890 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e  ors can be used.
1c8a0 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20  .**.** Prior to 
1c8b0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
1c8c0 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f  .7.10, the Windo
1c8d0 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20  ws OS interface 
1c8e0 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20  layer called.** 
1c8f0 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
1c900 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64  c() and free() d
1c910 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e  irectly when con
1c920 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e  verting.** filen
1c930 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65  ames between the
1c940 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
1c950 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  used by SQLite.*
1c960 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66  * and whatever f
1c970 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67  ilename encoding
1c980 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
1c990 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f  particular Windo
1c9a0 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69  ws.** installati
1c9b0 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f  on.  Memory allo
1c9c0 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65  cation errors we
1c9d0 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74  re detected, but
1c9e0 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 65  .** they were re
1c9f0 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b  ported back as [
1ca00 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
1ca10 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49   or.** [SQLITE_I
1ca20 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61  OERR] rather tha
1ca30 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  n [SQLITE_NOMEM]
1ca40 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e  ..**.** The poin
1ca50 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ter arguments to
1ca60 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1ca70 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
1ca80 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73  ealloc()].** mus
1ca90 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c  t be either NULL
1caa0 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72   or else pointer
1cab0 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
1cac0 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63  a prior.** invoc
1cad0 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
1cae0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b  3_malloc()] or [
1caf0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1cb00 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20  )] that have.** 
1cb10 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c  not yet been rel
1cb20 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eased..**.** The
1cb30 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
1cb40 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72  t not read or wr
1cb50 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a  ite any part of.
1cb60 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65  ** a block of me
1cb70 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61  mory after it ha
1cb80 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20  s been released 
1cb90 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
1cba0 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71  3_free()] or [sq
1cbb0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1cbc0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
1cbd0 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  e3_malloc(int);.
1cbe0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61  void *sqlite3_ma
1cbf0 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75  lloc64(sqlite3_u
1cc00 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71  int64);.void *sq
1cc10 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f  lite3_realloc(vo
1cc20 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  id*, int);.void 
1cc30 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
1cc40 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65  64(void*, sqlite
1cc50 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20  3_uint64);.void 
1cc60 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69  sqlite3_free(voi
1cc70 64 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e  d*);.sqlite3_uin
1cc80 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  t64 sqlite3_msiz
1cc90 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e(void*);../*.**
1cca0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
1ccb0 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74  y Allocator Stat
1ccc0 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  istics.**.** SQL
1ccd0 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65  ite provides the
1cce0 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65  se two interface
1ccf0 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20  s for reporting 
1cd00 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a  on the status.**
1cd10 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
1cd20 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c  _malloc()], [sql
1cd30 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e  ite3_free()], an
1cd40 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
1cd50 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65  oc()].** routine
1cd60 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68  s, which form th
1cd70 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  e built-in memor
1cd80 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
1cd90 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  system..**.** ^T
1cda0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
1cdb0 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69  ry_used()] routi
1cdc0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
1cdd0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a  umber of bytes.*
1cde0 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72  * of memory curr
1cdf0 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e  ently outstandin
1ce00 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20  g (malloced but 
1ce10 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e  not freed)..** ^
1ce20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
1ce30 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
1ce40 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1ce50 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
1ce60 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
1ce70 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1ce80 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d   since the high-
1ce90 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61  water mark.** wa
1cea0 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e  s last reset.  ^
1ceb0 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
1cec0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
1ced0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61  memory_used()] a
1cee0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  nd.** [sqlite3_m
1cef0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1cf00 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f  )] include any o
1cf10 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64  verhead.** added
1cf20 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74   by SQLite in it
1cf30 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
1cf40 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
1cf50 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e  loc()],.** but n
1cf60 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65  ot overhead adde
1cf70 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64  d by the any und
1cf80 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c  erlying system l
1cf90 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e  ibrary.** routin
1cfa0 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  es that [sqlite3
1cfb0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63  _malloc()] may c
1cfc0 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  all..**.** ^The 
1cfd0 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65  memory high-wate
1cfe0 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20  r mark is reset 
1cff0 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  to the current v
1d000 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69  alue of.** [sqli
1d010 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1d020 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  )] if and only i
1d030 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1d040 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  to.** [sqlite3_m
1d050 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1d060 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68  )] is true.  ^Th
1d070 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1d080 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
1d090 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1d0a0 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68  (1)] is the high
1d0b0 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70  -water mark.** p
1d0c0 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65  rior to the rese
1d0d0 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  t..*/.sqlite3_in
1d0e0 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
1d0f0 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73  ry_used(void);.s
1d100 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
1d110 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1d120 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46  water(int resetF
1d130 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  lag);../*.** CAP
1d140 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61  I3REF: Pseudo-Ra
1d150 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65  ndom Number Gene
1d160 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  rator.**.** SQLi
1d170 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69  te contains a hi
1d180 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
1d190 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20  o-random number 
1d1a0 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29  generator (PRNG)
1d1b0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65   used to.** sele
1d1c0 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44  ct random [ROWID
1d1d0 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20   | ROWIDs] when 
1d1e0 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65  inserting new re
1d1f0 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62  cords into a tab
1d200 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61  le that.** alrea
1d210 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67  dy uses the larg
1d220 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f  est possible [RO
1d230 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20  WID].  The PRNG 
1d240 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72  is also used for
1d250 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e  .** the build-in
1d260 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61   random() and ra
1d270 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66  ndomblob() SQL f
1d280 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20  unctions.  This 
1d290 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
1d2a0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
1d2b0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73   to access the s
1d2c0 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68  ame PRNG for oth
1d2d0 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a  er purposes..**.
1d2e0 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68  ** ^A call to th
1d2f0 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65  is routine store
1d300 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e  s N bytes of ran
1d310 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66  domness into buf
1d320 66 65 72 20 50 2e 0a 2a 2a 20 5e 49 66 20 4e 20  fer P..** ^If N 
1d330 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65  is less than one
1d340 2c 20 74 68 65 6e 20 50 20 63 61 6e 20 62 65 20  , then P can be 
1d350 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1d360 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72  **.** ^If this r
1d370 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62  outine has not b
1d380 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63  een previously c
1d390 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20  alled or if the 
1d3a0 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c  previous.** call
1d3b0 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e   had N less than
1d3c0 20 6f 6e 65 2c 20 74 68 65 6e 20 74 68 65 20 50   one, then the P
1d3d0 52 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 73  RNG is seeded us
1d3e0 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 0a 2a  ing randomness.*
1d3f0 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  * obtained from 
1d400 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20  the xRandomness 
1d410 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65  method of the de
1d420 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
1d430 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  fs] object..** ^
1d440 49 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  If the previous 
1d450 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75  call to this rou
1d460 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f 66  tine had an N of
1d470 20 31 20 6f 72 20 6d 6f 72 65 20 74 68 65 6e 0a   1 or more then.
1d480 2a 2a 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61  ** the pseudo-ra
1d490 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65  ndomness is gene
1d4a0 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61  rated.** interna
1d4b0 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20  lly and without 
1d4c0 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20  recourse to the 
1d4d0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52  [sqlite3_vfs] xR
1d4e0 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74  andomness.** met
1d4f0 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  hod..*/.void sql
1d500 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28  ite3_randomness(
1d510 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b  int N, void *P);
1d520 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1d530 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41  : Compile-Time A
1d540 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c  uthorization Cal
1d550 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
1d560 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73  is routine regis
1d570 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a  ters an authoriz
1d580 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68  er callback with
1d590 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
1d5a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1d5b0 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64  ction], supplied
1d5c0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
1d5d0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
1d5e0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1d5f0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  ack is invoked a
1d600 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  s SQL statements
1d610 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69   are being compi
1d620 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  led.** by [sqlit
1d630 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
1d640 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73   its variants [s
1d650 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1d660 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  2()],.** [sqlite
1d670 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61  3_prepare16()] a
1d680 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
1d690 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41  are16_v2()].  ^A
1d6a0 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69  t various.** poi
1d6b0 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63  nts during the c
1d6c0 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65  ompilation proce
1d6d0 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20  ss, as logic is 
1d6e0 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a  being created.**
1d6f0 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
1d700 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  ous actions, the
1d710 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1d720 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
1d730 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f  to.** see if tho
1d740 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61  se actions are a
1d750 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75  llowed.  ^The au
1d760 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1d770 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  k should.** retu
1d780 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74  rn [SQLITE_OK] t
1d790 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69  o allow the acti
1d7a0 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  on, [SQLITE_IGNO
1d7b0 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20  RE] to disallow 
1d7c0 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
1d7d0 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77  action but allow
1d7e0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1d7f0 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74  nt to continue t
1d800 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  o be.** compiled
1d810 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
1d820 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20  Y] to cause the 
1d830 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65  entire SQL state
1d840 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65  ment to be.** re
1d850 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65  jected with an e
1d860 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61  rror.  ^If the a
1d870 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1d880 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ck returns.** an
1d890 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
1d8a0 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  an [SQLITE_IGNOR
1d8b0 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  E], [SQLITE_OK],
1d8c0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
1d8d0 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73  ].** then the [s
1d8e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1d8f0 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
1d900 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
1d910 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75  ggered.** the au
1d920 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
1d930 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
1d940 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
1d950 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
1d960 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
1d970 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e  E_OK], that mean
1d980 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  s the operation.
1d990 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20  ** requested is 
1d9a0 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63  ok.  ^When the c
1d9b0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1d9c0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
1d9d0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
1d9e0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1d9f0 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
1da00 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
1da10 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
1da20 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
1da30 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
1da40 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
1da50 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65  .** access is de
1da60 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  nied. .**.** ^Th
1da70 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1da80 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
1da90 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1daa0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
1dab0 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
1dac0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1dad0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
1dae0 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65   interface. ^The
1daf0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1db00 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  r.** to the call
1db10 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
1db20 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20  er [SQLITE_COPY 
1db30 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74  | action code] t
1db40 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
1db50 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
1db60 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
1db70 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68  horized. ^The th
1db80 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74  ird through sixt
1db90 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  h parameters.** 
1dba0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
1dbb0 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  are zero-termina
1dbc0 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
1dbd0 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f   contain additio
1dbe0 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61  nal.** details a
1dbf0 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20  bout the action 
1dc00 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
1dc10 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1dc20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
1dc30 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20  SQLITE_READ].** 
1dc40 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
1dc50 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1dc60 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
1dc70 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
1dc80 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d  tatement] statem
1dc90 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74  ent is construct
1dca0 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65  ed to substitute
1dcb0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65  .** a NULL value
1dcc0 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
1dcd0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
1dce0 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  at would have.**
1dcf0 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53   been read if [S
1dd00 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65  QLITE_OK] had be
1dd10 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  en returned.  Th
1dd20 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  e [SQLITE_IGNORE
1dd30 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20  ].** return can 
1dd40 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20  be used to deny 
1dd50 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65  an untrusted use
1dd60 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69  r access to indi
1dd70 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e  vidual.** column
1dd80 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a  s of a table..**
1dd90 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
1dda0 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
1ddb0 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20  DELETE] and the 
1ddc0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1ddd0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  .** [SQLITE_IGNO
1dde0 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45  RE] then the [DE
1ddf0 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20  LETE] operation 
1de00 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65  proceeds but the
1de10 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70  .** [truncate op
1de20 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64  timization] is d
1de30 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20  isabled and all 
1de40 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64  rows are deleted
1de50 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a   individually..*
1de60 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a  *.** An authoriz
1de70 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20  er is used when 
1de80 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1de90 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a   | preparing].**
1dea0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1deb0 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65  from an untruste
1dec0 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73  d source, to ens
1ded0 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ure that the SQL
1dee0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64   statements.** d
1def0 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63  o not try to acc
1df00 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72  ess data they ar
1df10 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f  e not allowed to
1df20 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68   see, or that th
1df30 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79  ey do not.** try
1df40 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69   to execute mali
1df50 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73  cious statements
1df60 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65   that damage the
1df70 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a   database.  For.
1df80 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  ** example, an a
1df90 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61  pplication may a
1dfa0 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65  llow a user to e
1dfb0 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a  nter arbitrary.*
1dfc0 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f  * SQL queries fo
1dfd0 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20  r evaluation by 
1dfe0 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74  a database.  But
1dff0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1e000 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e   does.** not wan
1e010 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65  t the user to be
1e020 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72   able to make ar
1e030 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20  bitrary changes 
1e040 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
1e050 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a  se.  An authoriz
1e060 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65  er could then be
1e070 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68   put in place wh
1e080 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d  ile the.** user-
1e090 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62  entered SQL is b
1e0a0 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  eing [sqlite3_pr
1e0b0 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64  epare | prepared
1e0c0 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c  ] that.** disall
1e0d0 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65  ows everything e
1e0e0 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73  xcept [SELECT] s
1e0f0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
1e100 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
1e110 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65  at need to proce
1e120 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72  ss SQL from untr
1e130 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a  usted sources.**
1e140 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73   might also cons
1e150 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65  ider lowering re
1e160 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73  source limits us
1e170 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
1e180 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d  it()].** and lim
1e190 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73  iting database s
1e1a0 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d  ize using the [m
1e1b0 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
1e1c0 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64  PRAGMA].** in ad
1e1d0 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20  dition to using 
1e1e0 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a  an authorizer..*
1e1f0 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69  *.** ^(Only a si
1e200 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ngle authorizer 
1e210 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20  can be in place 
1e220 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  on a database co
1e230 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61  nnection.** at a
1e240 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c   time.  Each cal
1e250 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  l to sqlite3_set
1e260 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72  _authorizer over
1e270 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65  rides the.** pre
1e280 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e  vious call.)^  ^
1e290 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68  Disable the auth
1e2a0 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c  orizer by instal
1e2b0 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c  ling a NULL call
1e2c0 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74  back..** The aut
1e2d0 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62  horizer is disab
1e2e0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
1e2f0 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  **.** The author
1e300 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  izer callback mu
1e310 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
1e320 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
1e330 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
1e340 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
1e350 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
1e360 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1e370 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ack..** Note tha
1e380 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
1e390 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
1e3a0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
1e3b0 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
1e3c0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1e3d0 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
1e3e0 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
1e3f0 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
1e400 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  graph..**.** ^Wh
1e410 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
1e420 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65  are_v2()] is use
1e430 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73  d to prepare a s
1e440 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a  tatement, the.**
1e450 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74   statement might
1e460 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20   be re-prepared 
1e470 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  during [sqlite3_
1e480 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61  step()] due to a
1e490 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e   .** schema chan
1e4a0 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  ge.  Hence, the 
1e4b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
1e4c0 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  ld ensure that t
1e4d0 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75  he.** correct au
1e4e0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1e4f0 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61  k remains in pla
1e500 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73  ce during the [s
1e510 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
1e520 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74  **.** ^Note that
1e530 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1e540 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1e550 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a  ked only during.
1e560 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1e570 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
1e580 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69  riants.  Authori
1e590 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a  zation is not.**
1e5a0 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e   performed durin
1e5b0 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c  g statement eval
1e5c0 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74  uation in [sqlit
1e5d0 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65  e3_step()], unle
1e5e0 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20  ss.** as stated 
1e5f0 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
1e600 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74  paragraph, sqlit
1e610 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65  e3_step() invoke
1e620 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65  s.** sqlite3_pre
1e630 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70  pare_v2() to rep
1e640 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
1e650 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d  nt after a schem
1e660 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74  a change..*/.int
1e670 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
1e680 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74  horizer(.  sqlit
1e690 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75  e3*,.  int (*xAu
1e6a0 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  th)(void*,int,co
1e6b0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1e6c0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1e6d0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a  *,const char*),.
1e6e0 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74    void *pUserDat
1e6f0 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  a.);../*.** CAPI
1e700 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
1e710 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a   Return Codes.**
1e720 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
1e730 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1e740 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
1e750 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20  lback function] 
1e760 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65  must.** return e
1e770 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b  ither [SQLITE_OK
1e780 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73  ] or one of thes
1e790 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20  e two constants 
1e7a0 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73  in order.** to s
1e7b0 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65  ignal SQLite whe
1e7c0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
1e7d0 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  action is permit
1e7e0 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ted.  See the.**
1e7f0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
1e800 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
1e810 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74  rizer documentat
1e820 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f  ion] for additio
1e830 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
1e840 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  on..**.** Note t
1e850 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  hat SQLITE_IGNOR
1e860 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61  E is also used a
1e870 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65  s a [conflict re
1e880 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a  solution mode].*
1e890 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  * returned from 
1e8a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61  the [sqlite3_vta
1e8b0 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d  b_on_conflict()]
1e8c0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23   interface..*/.#
1e8d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
1e8e0 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72  NY   1   /* Abor
1e8f0 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
1e900 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ent with an erro
1e910 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
1e920 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f  ITE_IGNORE 2   /
1e930 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63  * Don't allow ac
1e940 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20  cess, but don't 
1e950 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f  generate an erro
1e960 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  r */../*.** CAPI
1e970 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
1e980 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a   Action Codes.**
1e990 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
1e9a0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1e9b0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
1e9c0 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
1e9d0 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68  k function.** th
1e9e0 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  at is invoked to
1e9f0 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61   authorize certa
1ea00 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  in SQL statement
1ea10 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a   actions.  The.*
1ea20 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
1ea30 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
1ea40 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
1ea50 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69   code that speci
1ea60 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74  fies.** what act
1ea70 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74  ion is being aut
1ea80 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20  horized.  These 
1ea90 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20  are the integer 
1eaa0 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61  action codes tha
1eab0 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  t.** the authori
1eac0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79  zer callback may
1ead0 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a   be passed..**.*
1eae0 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63  * These action c
1eaf0 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69  ode values signi
1eb00 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  fy what kind of 
1eb10 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20  operation is to 
1eb20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64  be.** authorized
1eb30 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34  .  The 3rd and 4
1eb40 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
1eb50 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69   the authorizati
1eb60 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  on.** callback f
1eb70 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20  unction will be 
1eb80 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55  parameters or NU
1eb90 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  LL depending on 
1eba0 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a  which of these.*
1ebb0 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20  * codes is used 
1ebc0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
1ebd0 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20  rameter.  ^(The 
1ebe0 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
1ebf0 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
1ec00 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
1ec10 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
1ec20 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c  atabase ("main",
1ec30 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e   "temp",.** etc.
1ec40 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e  ) if applicable.
1ec50 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72  )^  ^The 6th par
1ec60 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
1ec70 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1ec80 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  k.** is the name
1ec90 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
1eca0 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
1ecb0 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
1ecc0 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68  nsible for.** th
1ecd0 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
1ece0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
1ecf0 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
1ed00 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
1ed10 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51  .** top-level SQ
1ed20 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a  L code..*/./****
1ed30 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ed40 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ed50 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a  ******* 3rd ****
1ed60 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a  ******** 4th ***
1ed70 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e  ********/.#defin
1ed80 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1ed90 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31  INDEX          1
1eda0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1edb0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
1edc0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1edd0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1ede0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20  ABLE          2 
1edf0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1ee00 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1ee10 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1ee20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1ee30 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20  MP_INDEX     3  
1ee40 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1ee50 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1ee60 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1ee70 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1ee80 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20  P_TABLE     4   
1ee90 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1eea0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1eeb0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1eec0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1eed0 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f  _TRIGGER   5   /
1eee0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
1eef0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1ef00 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1ef10 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1ef20 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a  VIEW      6   /*
1ef30 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
1ef40 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1ef50 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ef60 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45  TE_CREATE_TRIGGE
1ef70 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  R        7   /* 
1ef80 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1ef90 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1efa0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1efb0 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20  E_CREATE_VIEW   
1efc0 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56          8   /* V
1efd0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1efe0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1eff0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f000 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
1f010 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61         9   /* Ta
1f020 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1f030 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1f040 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f050 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20  DROP_INDEX      
1f060 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64       10   /* Ind
1f070 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1f080 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1f090 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1f0a0 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ROP_TABLE       
1f0b0 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c      11   /* Tabl
1f0c0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1f0d0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1f0e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1f0f0 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  OP_TEMP_INDEX   
1f100 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78     12   /* Index
1f110 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1f120 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1f130 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1f140 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  P_TEMP_TABLE    
1f150 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    13   /* Table 
1f160 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1f170 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1f180 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1f190 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
1f1a0 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72   14   /* Trigger
1f1b0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1f1c0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1f1d0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1f1e0 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20  TEMP_VIEW       
1f1f0 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  15   /* View Nam
1f200 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1f210 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1f220 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1f230 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31  RIGGER         1
1f240 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  6   /* Trigger N
1f250 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1f260 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1f270 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49  e SQLITE_DROP_VI
1f280 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37  EW            17
1f290 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1f2a0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1f2b0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f2c0 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20   SQLITE_INSERT  
1f2d0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20               18 
1f2e0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1f2f0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1f300 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f310 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20  SQLITE_PRAGMA   
1f320 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20              19  
1f330 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20   /* Pragma Name 
1f340 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e      1st arg or N
1f350 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ULL */.#define S
1f360 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20  QLITE_READ      
1f370 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20             20   
1f380 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1f390 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
1f3a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f3b0 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20  LITE_SELECT     
1f3c0 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f            21   /
1f3d0 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
1f3e0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1f3f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f400 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20  ITE_TRANSACTION 
1f410 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a           22   /*
1f420 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
1f430 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1f440 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f450 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20  TE_UPDATE       
1f460 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
1f470 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1f480 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
1f490 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f4a0 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20  E_ATTACH        
1f4b0 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46         24   /* F
1f4c0 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e  ilename        N
1f4d0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1f4e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f4f0 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20  _DETACH         
1f500 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61        25   /* Da
1f510 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55  tabase Name   NU
1f520 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1f530 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f540 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20  ALTER_TABLE     
1f550 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74       26   /* Dat
1f560 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62  abase Name   Tab
1f570 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1f580 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
1f590 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  EINDEX          
1f5a0 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65      27   /* Inde
1f5b0 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  x Name      NULL
1f5c0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1f5d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
1f5e0 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20  ALYZE           
1f5f0 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65     28   /* Table
1f600 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1f610 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1f620 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1f630 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ATE_VTABLE      
1f640 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20    29   /* Table 
1f650 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
1f660 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1f670 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1f680 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  _VTABLE         
1f690 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   30   /* Table N
1f6a0 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
1f6b0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1f6c0 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54  ine SQLITE_FUNCT
1f6d0 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  ION             
1f6e0 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  31   /* NULL    
1f6f0 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e          Function
1f700 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69   Name   */.#defi
1f710 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f  ne SQLITE_SAVEPO
1f720 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33  INT            3
1f730 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
1f740 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74         Savepoint
1f750 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e   Name  */.#defin
1f760 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20  e SQLITE_COPY   
1f770 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
1f780 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20     /* No longer 
1f790 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  used */.#define 
1f7a0 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45  SQLITE_RECURSIVE
1f7b0 20 20 20 20 20 20 20 20 20 20 20 20 33 33 20 20              33  
1f7c0 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
1f7d0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1f7e0 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41      */../*.** CA
1f7f0 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20  PI3REF: Tracing 
1f800 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75  And Profiling Fu
1f810 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
1f820 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67  ese routines reg
1f830 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  ister callback f
1f840 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61  unctions that ca
1f850 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a  n be used for.**
1f860 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f   tracing and pro
1f870 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75  filing the execu
1f880 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74  tion of SQL stat
1f890 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
1f8a0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
1f8b0 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
1f8c0 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  by sqlite3_trace
1f8d0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74  () is invoked at
1f8e0 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65  .** various time
1f8f0 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74  s when an SQL st
1f900 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67  atement is being
1f910 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33   run by [sqlite3
1f920 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68  _step()]..** ^Th
1f930 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  e sqlite3_trace(
1f940 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  ) callback is in
1f950 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46  voked with a UTF
1f960 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  -8 rendering of 
1f970 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  the.** SQL state
1f980 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65  ment text as the
1f990 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74   statement first
1f9a0 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e   begins executin
1f9b0 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e  g..** ^(Addition
1f9c0 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  al sqlite3_trace
1f9d0 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67  () callbacks mig
1f9e0 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65  ht occur.** as e
1f9f0 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75  ach triggered su
1fa00 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65  bprogram is ente
1fa10 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61  red.  The callba
1fa20 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73  cks for triggers
1fa30 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54  .** contain a UT
1fa40 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20  F-8 SQL comment 
1fa50 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20  that identifies 
1fa60 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a  the trigger.)^.*
1fa70 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
1fa80 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49  _TRACE_SIZE_LIMI
1fa90 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  T] compile-time 
1faa0 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
1fab0 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74  ed to limit.** t
1fac0 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f  he length of [bo
1fad0 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65  und parameter] e
1fae0 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20  xpansion in the 
1faf0 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65  output of sqlite
1fb00 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a  3_trace()..**.**
1fb10 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
1fb20 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
1fb30 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72  ed by sqlite3_pr
1fb40 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b  ofile() is invok
1fb50 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51  ed.** as each SQ
1fb60 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
1fb70 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66  shes.  ^The prof
1fb80 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  ile callback con
1fb90 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69  tains.** the ori
1fba0 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20  ginal statement 
1fbb0 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69  text and an esti
1fbc0 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f  mate of wall-clo
1fbd0 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f  ck time.** of ho
1fbe0 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74  w long that stat
1fbf0 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75  ement took to ru
1fc00 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  n.  ^The profile
1fc10 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d   callback.** tim
1fc20 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66  e is in units of
1fc30 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f   nanoseconds, ho
1fc40 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e  wever the curren
1fc50 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
1fc60 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61  .** is only capa
1fc70 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ble of milliseco
1fc80 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f  nd resolution so
1fc90 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73   the six least s
1fca0 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69  ignificant.** di
1fcb0 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65  gits in the time
1fcc0 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73   are meaningless
1fcd0 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
1fce0 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  ns of SQLite.** 
1fcf0 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72  might provide gr
1fd00 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e  eater resolution
1fd10 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72   on the profiler
1fd20 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a   callback.  The.
1fd30 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  ** sqlite3_profi
1fd40 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  le() function is
1fd50 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65   considered expe
1fd60 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a  rimental and is.
1fd70 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  ** subject to ch
1fd80 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76  ange in future v
1fd90 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
1fda0 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  e..*/.void *sqli
1fdb0 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65  te3_trace(sqlite
1fdc0 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65  3*, void(*xTrace
1fdd0 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
1fde0 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51  ar*), void*);.SQ
1fdf0 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
1fe00 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  L void *sqlite3_
1fe10 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a  profile(sqlite3*
1fe20 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66  ,.   void(*xProf
1fe30 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ile)(void*,const
1fe40 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75   char*,sqlite3_u
1fe50 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a  int64), void*);.
1fe60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1fe70 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20   Query Progress 
1fe80 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
1fe90 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f  ^The sqlite3_pro
1fea0 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c  gress_handler(D,
1feb0 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65  N,X,P) interface
1fec0 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
1fed0 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
1fee0 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64   X to be invoked
1fef0 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75   periodically du
1ff00 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e  ring long runnin
1ff10 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  g calls to.** [s
1ff20 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
1ff30 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1ff40 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65   and [sqlite3_ge
1ff50 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a  t_table()] for.*
1ff60 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1ff70 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61  ction D.  An exa
1ff80 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69  mple use for thi
1ff90 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  s.** interface i
1ffa0 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20  s to keep a GUI 
1ffb0 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61  updated during a
1ffc0 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a   large query..**
1ffd0 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74  .** ^The paramet
1ffe0 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74  er P is passed t
1fff0 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e  hrough as the on
20000 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ly parameter to 
20010 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  the .** callback
20020 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54   function X.  ^T
20030 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69  he parameter N i
20040 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74  s the approximat
20050 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20  e number of .** 
20060 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65  [virtual machine
20070 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74   instructions] t
20080 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65  hat are evaluate
20090 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73  d between succes
200a0 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  sive.** invocati
200b0 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62  ons of the callb
200c0 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73  ack X.  ^If N is
200d0 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74   less than one t
200e0 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73  hen the progress
200f0 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64  .** handler is d
20100 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  isabled..**.** ^
20110 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72  Only a single pr
20120 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d  ogress handler m
20130 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74  ay be defined at
20140 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a   one time per.**
20150 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
20160 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20  ction]; setting 
20170 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68  a new progress h
20180 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74  andler cancels t
20190 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20  he.** old one.  
201a0 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74  ^Setting paramet
201b0 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73  er X to NULL dis
201c0 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65  ables the progre
201d0 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e  ss handler..** ^
201e0 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
201f0 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73  dler is also dis
20200 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67  abled by setting
20210 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65   N to a value le
20220 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a  ss.** than 1..**
20230 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67  .** ^If the prog
20240 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65  ress callback re
20250 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
20260 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  the operation is
20270 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e  .** interrupted.
20280 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63    This feature c
20290 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d  an be used to im
202a0 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61  plement a.** "Ca
202b0 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20  ncel" button on 
202c0 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64  a GUI progress d
202d0 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a  ialog box..**.**
202e0 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   The progress ha
202f0 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  ndler callback m
20300 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
20310 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
20320 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
20330 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
20340 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
20350 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
20360 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  r..** Note that 
20370 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20380 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
20390 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
203a0 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
203b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
203c0 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
203d0 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
203e0 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
203f0 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20  aph..**.*/.void 
20400 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
20410 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
20420 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76  *, int, int(*)(v
20430 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  oid*), void*);..
20440 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
20450 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61  Opening A New Da
20460 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
20470 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  n.**.** ^These r
20480 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20  outines open an 
20490 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
204a0 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65  file as specifie
204b0 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c  d by the .** fil
204c0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20  ename argument. 
204d0 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72  ^The filename ar
204e0 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70  gument is interp
204f0 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66  reted as UTF-8 f
20500 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
20510 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
20520 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61  _open_v2() and a
20530 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  s UTF-16 in the 
20540 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f  native byte.** o
20550 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33  rder for sqlite3
20560 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b  _open16(). ^(A [
20570 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
20580 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75  ion] handle is u
20590 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e  sually.** return
205a0 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65  ed in *ppDb, eve
205b0 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63  n if an error oc
205c0 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  curs.  The only 
205d0 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61  exception is tha
205e0 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69  t.** if SQLite i
205f0 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
20600 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68  cate memory to h
20610 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  old the [sqlite3
20620 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e  ] object,.** a N
20630 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74  ULL will be writ
20640 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69  ten into *ppDb i
20650 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e  nstead of a poin
20660 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
20670 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29  te3].** object.)
20680 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62  ^ ^(If the datab
20690 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61  ase is opened (a
206a0 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73  nd/or created) s
206b0 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65  uccessfully, the
206c0 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  n.** [SQLITE_OK]
206d0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
206e0 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
206f0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
20700 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20  rned.)^ ^The.** 
20710 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
20720 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65  )] or [sqlite3_e
20730 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69  rrmsg16()] routi
20740 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nes can be used 
20750 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20  to obtain.** an 
20760 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65  English language
20770 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20   description of 
20780 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77  the error follow
20790 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66  ing a failure of
207a0 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73   any.** of the s
207b0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f  qlite3_open() ro
207c0 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  utines..**.** ^T
207d0 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64  he default encod
207e0 69 6e 67 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ing will be UTF-
207f0 38 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 20  8 for databases 
20800 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a  created using.**
20810 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
20820 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
20830 76 32 28 29 2e 20 20 5e 54 68 65 20 64 65 66 61  v2().  ^The defa
20840 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72  ult encoding for
20850 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 63 72   databases.** cr
20860 65 61 74 65 64 20 75 73 69 6e 67 20 73 71 6c 69  eated using sqli
20870 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c  te3_open16() wil
20880 6c 20 62 65 20 55 54 46 2d 31 36 20 69 6e 20 74  l be UTF-16 in t
20890 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
208a0 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74  rder..**.** Whet
208b0 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72  her or not an er
208c0 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20  ror occurs when 
208d0 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65  it is opened, re
208e0 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63  sources.** assoc
208f0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
20900 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
20910 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75  ion] handle shou
20920 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62  ld be released b
20930 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20  y.** passing it 
20940 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  to [sqlite3_clos
20950 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20  e()] when it is 
20960 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72  no longer requir
20970 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
20980 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
20990 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20  interface works 
209a0 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65  like sqlite3_ope
209b0 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  n().** except th
209c0 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77  at it accepts tw
209d0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72  o additional par
209e0 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69  ameters for addi
209f0 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a  tional control.*
20a00 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64  * over the new d
20a10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20a20 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73  on.  ^(The flags
20a30 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
20a40 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
20a50 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20  () can take one 
20a60 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77  of.** the follow
20a70 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73  ing three values
20a80 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  , optionally com
20a90 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a  bined with the .
20aa0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
20ab0 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  NOMUTEX], [SQLIT
20ac0 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
20ad0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
20ae0 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a  SHAREDCACHE],.**
20af0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
20b00 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64  IVATECACHE], and
20b10 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  /or [SQLITE_OPEN
20b20 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a  _URI] flags:)^.*
20b30 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c  *.** <dl>.** ^(<
20b40 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
20b50 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a  READONLY]</dt>.*
20b60 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
20b70 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20  se is opened in 
20b80 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20  read-only mode. 
20b90 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
20ba0 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72   does not.** alr
20bb0 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65  eady exist, an e
20bc0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
20bd0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
20be0 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
20bf0 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74  N_READWRITE]</dt
20c00 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
20c10 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
20c20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
20c30 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69  writing if possi
20c40 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a  ble, or reading.
20c50 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66  ** only if the f
20c60 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f  ile is write pro
20c70 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70  tected by the op
20c80 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
20c90 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61   In either.** ca
20ca0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
20cb0 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69  must already exi
20cc0 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e  st, otherwise an
20cd0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
20ce0 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
20cf0 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
20d00 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
20d10 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
20d20 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  EATE]</dt>.** <d
20d30 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
20d40 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
20d50 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
20d60 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64  , and is created
20d70 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e   if.** it does n
20d80 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ot already exist
20d90 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65  . This is the be
20da0 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61  havior that is a
20db0 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a  lways used for.*
20dc0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
20dd0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
20de0 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  n16().</dd>)^.**
20df0 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20   </dl>.**.** If 
20e00 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
20e10 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
20e20 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e  n_v2() is not on
20e30 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62  e of the.** comb
20e40 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61  inations shown a
20e50 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  bove optionally 
20e60 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74  combined with ot
20e70 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  her.** [SQLITE_O
20e80 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53  PEN_READONLY | S
20e90 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74  QLITE_OPEN_* bit
20ea0 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62  s].** then the b
20eb0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
20ec0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ined..**.** ^If 
20ed0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
20ee0 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  _NOMUTEX] flag i
20ef0 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20  s set, then the 
20f00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
20f10 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20  ion.** opens in 
20f20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  the multi-thread
20f30 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
20f40 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  ] as long as the
20f50 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a   single-thread.*
20f60 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62  * mode has not b
20f70 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69  een set at compi
20f80 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
20f90 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a  -time.  ^If the.
20fa0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
20fb0 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20  FULLMUTEX] flag 
20fc0 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20  is set then the 
20fd0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
20fe0 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20  ion opens.** in 
20ff0 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
21000 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
21010 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68  unless single-th
21020 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76  read was.** prev
21030 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20  iously selected 
21040 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
21050 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a  or start-time..*
21060 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
21070 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
21080 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
21090 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
210a0 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c  tion to be.** el
210b0 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73  igible to use [s
210c0 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
210d0 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ], regardless of
210e0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
210f0 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20  shared.** cache 
21100 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67  is enabled using
21110 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
21120 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d  _shared_cache()]
21130 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49  .  ^The.** [SQLI
21140 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
21150 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
21160 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
21170 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74  onnection to not
21180 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20  .** participate 
21190 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  in [shared cache
211a0 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69   mode] even if i
211b0 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  t is enabled..**
211c0 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
211d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
211e0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
211f0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
21200 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
21210 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
21220 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61  efines the opera
21230 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
21240 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68  rface that.** th
21250 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
21260 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64  onnection should
21270 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66   use.  ^If the f
21280 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
21290 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  is.** a NULL poi
212a0 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65  nter then the de
212b0 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
212c0 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73  fs] object is us
212d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
212e0 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a  e filename is ":
212f0 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61  memory:", then a
21300 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
21310 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  ary in-memory da
21320 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65  tabase.** is cre
21330 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e  ated for the con
21340 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20  nection.  ^This 
21350 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
21360 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77  se will vanish w
21370 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  hen.** the datab
21380 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
21390 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72  s closed.  Futur
213a0 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
213b0 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61  Lite might.** ma
213c0 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69  ke use of additi
213d0 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c  onal special fil
213e0 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69  enames that begi
213f0 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63  n with the ":" c
21400 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20  haracter..** It 
21410 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
21420 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62  hat when a datab
21430 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74  ase filename act
21440 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e  ually does begin
21450 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63   with.** a ":" c
21460 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f  haracter you sho
21470 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66  uld prefix the f
21480 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70  ilename with a p
21490 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a  athname such as.
214a0 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64  ** "./" to avoid
214b0 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a   ambiguity..**.*
214c0 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
214d0 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73  me is an empty s
214e0 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72  tring, then a pr
214f0 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
21500 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61  .** on-disk data
21510 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65  base will be cre
21520 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69  ated.  ^This pri
21530 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69  vate database wi
21540 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74  ll be.** automat
21550 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61  ically deleted a
21560 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61  s soon as the da
21570 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
21580 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
21590 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
215a0 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70  es in sqlite3_op
215b0 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46  en()]] <h3>URI F
215c0 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a  ilenames</h3>.**
215d0 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c  .** ^If [URI fil
215e0 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74  ename] interpret
215f0 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
21600 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61  , and the filena
21610 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62  me argument.** b
21620 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65  egins with "file
21630 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c  :", then the fil
21640 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72  ename is interpr
21650 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e  eted as a URI. ^
21660 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  URI.** filename 
21670 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
21680 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
21690 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
216a0 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65  I] flag is.** se
216b0 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20  t in the fourth 
216c0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
216d0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f  te3_open_v2(), o
216e0 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62  r if it has.** b
216f0 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62  een enabled glob
21700 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b  ally using the [
21710 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
21720 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74  I] option with t
21730 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
21740 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20  onfig()] method 
21750 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  or by the [SQLIT
21760 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69  E_USE_URI] compi
21770 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a  le-time option..
21780 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20  ** As of SQLite 
21790 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55  version 3.7.7, U
217a0 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65  RI filename inte
217b0 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75  rpretation is tu
217c0 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64  rned off.** by d
217d0 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75  efault, but futu
217e0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
217f0 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62  QLite might enab
21800 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a  le URI filename.
21810 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  ** interpretatio
21820 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53  n by default.  S
21830 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ee "[URI filenam
21840 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f  es]" for additio
21850 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
21860 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69  on..**.** URI fi
21870 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73  lenames are pars
21880 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  ed according to 
21890 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68  RFC 3986. ^If th
218a0 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61  e URI contains a
218b0 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20  n.** authority, 
218c0 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20  then it must be 
218d0 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20  either an empty 
218e0 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74  string or the st
218f0 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68  ring .** "localh
21900 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75  ost". ^If the au
21910 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61  thority is not a
21920 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
21930 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61  r "localhost", a
21940 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72  n .** error is r
21950 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63  eturned to the c
21960 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67  aller. ^The frag
21970 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  ment component o
21980 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20  f a URI, if .** 
21990 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f  present, is igno
219a0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  red..**.** ^SQLi
219b0 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74 68  te uses the path
219c0 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68   component of th
219d0 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d  e URI as the nam
219e0 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69  e of the disk fi
219f0 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74  le.** which cont
21a00 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 73  ains the databas
21a10 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  e. ^If the path 
21a20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f  begins with a '/
21a30 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a  ' character, .**
21a40 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65   then it is inte
21a50 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 62  rpreted as an ab
21a60 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66  solute path. ^If
21a70 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e   the path does n
21a80 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74  ot begin .** wit
21a90 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67  h a '/' (meaning
21aa0 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
21ab0 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f  ity section is o
21ac0 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
21ad0 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  URI).** then the
21ae0 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 72   path is interpr
21af0 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 69  eted as a relati
21b00 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f  ve path. .** ^(O
21b10 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66  n windows, the f
21b20 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  irst component o
21b30 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61  f an absolute pa
21b40 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76  th .** is a driv
21b50 65 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20  e specification 
21b60 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a  (e.g. "C:").)^.*
21b70 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20  *.** [[core URI 
21b80 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
21b90 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20  ]].** The query 
21ba0 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
21bb0 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70  RI may contain p
21bc0 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61  arameters that a
21bd0 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a  re interpreted.*
21be0 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c 69  * either by SQLi
21bf0 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79  te itself, or by
21c00 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d   a [VFS | custom
21c10 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
21c20 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  ion]..** SQLite 
21c30 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d 69 6e  and its built-in
21c40 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72 70 72   [VFSes] interpr
21c50 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  et the.** follow
21c60 69 6e 67 20 71 75 65 72 79 20 70 61 72 61 6d 65  ing query parame
21c70 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ters:.**.** <ul>
21c80 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66  .**   <li> <b>vf
21c90 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73  s</b>: ^The "vfs
21ca0 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  " parameter may 
21cb0 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69  be used to speci
21cc0 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a  fy the name of.*
21cd0 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65  *     a VFS obje
21ce0 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73  ct that provides
21cf0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
21d00 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
21d10 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20  that should.**  
21d20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63     be used to ac
21d30 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
21d40 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20  e file on disk. 
21d50 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ^If this option 
21d60 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20  is set to.**    
21d70 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
21d80 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
21d90 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
21da0 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20   ^Specifying an 
21db0 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56  unknown.**     V
21dc0 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20  FS is an error. 
21dd0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
21de0 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
21df0 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e  d the vfs option
21e00 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65   is.**     prese
21e10 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53  nt, then the VFS
21e20 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
21e30 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70  e option takes p
21e40 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a  recedence over.*
21e50 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20  *     the value 
21e60 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f  passed as the fo
21e70 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
21e80 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
21e90 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69  2()..**.**   <li
21ea0 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e  > <b>mode</b>: ^
21eb0 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65  (The mode parame
21ec0 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74  ter may be set t
21ed0 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22  o either "ro", "
21ee0 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63  rw",.**     "rwc
21ef0 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20  ", or "memory". 
21f00 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65  Attempting to se
21f10 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65  t it to any othe
21f20 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20  r value is.**   
21f30 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a    an error)^. .*
21f40 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69  *     ^If "ro" i
21f50 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65  s specified, the
21f60 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
21f70 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
21f80 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61  d-only .**     a
21f90 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69  ccess, just as i
21fa0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
21fb0 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61  EN_READONLY] fla
21fc0 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69  g had been set i
21fd0 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68  n the .**     th
21fe0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
21ff0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
22000 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20  ). ^If the mode 
22010 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f  option is set to
22020 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74   .**     "rw", t
22030 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
22040 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
22050 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e  ead-write (but n
22060 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20  ot create) .**  
22070 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66     access, as if
22080 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
22090 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20  DWRITE (but not 
220a0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
220b0 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20  TE) had .**     
220c0 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65  been set. ^Value
220d0 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61   "rwc" is equiva
220e0 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
220f0 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c  both .**     SQL
22100 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
22110 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50  TE and SQLITE_OP
22120 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20  EN_CREATE.  ^If 
22130 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20  the mode option 
22140 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f  is.**     set to
22150 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61   "memory" then a
22160 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79   pure [in-memory
22170 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20   database] that 
22180 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20  never reads.**  
22190 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f     or writes fro
221a0 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20  m disk is used. 
221b0 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20  ^It is an error 
221c0 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c  to specify a val
221d0 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68  ue for.**     th
221e0 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72  e mode parameter
221f0 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65   that is less re
22200 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74  strictive than t
22210 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79  hat specified by
22220 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67  .**     the flag
22230 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20  s passed in the 
22240 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
22250 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
22260 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
22270 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a  i> <b>cache</b>:
22280 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61   ^The cache para
22290 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
222a0 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72   to either "shar
222b0 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70  ed" or.**     "p
222c0 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e  rivate". ^Settin
222d0 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22  g it to "shared"
222e0 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
222f0 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a  o setting the.**
22300 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
22310 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74  _SHAREDCACHE bit
22320 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72   in the flags ar
22330 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f  gument passed to
22340 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f  .**     sqlite3_
22350 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74  open_v2(). ^Sett
22360 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61  ing the cache pa
22370 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76  rameter to "priv
22380 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20  ate" is .**     
22390 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
223a0 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45  tting the SQLITE
223b0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
223c0 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e  HE bit..**     ^
223d0 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
223e0 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
223f0 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72   the "cache" par
22400 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e  ameter is presen
22410 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52  t in.**     a UR
22420 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20  I filename, its 
22430 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20  value overrides 
22440 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65 71  any behavior req
22450 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e  uested by settin
22460 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  g.**     SQLITE_
22470 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
22480 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e  E or SQLITE_OPEN
22490 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61  _SHAREDCACHE fla
224a0 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c  g..**.**  <li> <
224b0 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65  b>psow</b>: ^The
224c0 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72 20   psow parameter 
224d0 69 6e 64 69 63 61 74 65 73 20 77 68 65 74 68 65  indicates whethe
224e0 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20  r or not the.** 
224f0 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65 20 6f      [powersafe o
22500 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70 65 72  verwrite] proper
22510 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65 73 20  ty does or does 
22520 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74 68 65  not apply to the
22530 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67 65 20  .**     storage 
22540 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68 20 74  media on which t
22550 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
22560 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20   resides..**.** 
22570 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c   <li> <b>nolock<
22580 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b  /b>: ^The nolock
22590 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
225a0 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 70 61  boolean query pa
225b0 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 77  rameter.**     w
225c0 68 69 63 68 20 69 66 20 73 65 74 20 64 69 73 61  hich if set disa
225d0 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e  bles file lockin
225e0 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f  g in rollback jo
225f0 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68  urnal modes.  Th
22600 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 73 65  is.**     is use
22610 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73 69 6e  ful for accessin
22620 67 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20  g a database on 
22630 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74 68 61  a filesystem tha
22640 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20  t does not.**   
22650 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e    support lockin
22660 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 44 61  g.  Caution:  Da
22670 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f  tabase corruptio
22680 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  n might result i
22690 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20  f two.**     or 
226a0 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73 20 77  more processes w
226b0 72 69 74 65 20 74 6f 20 74 68 65 20 73 61 6d 65  rite to the same
226c0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6e   database and an
226d0 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a  y one of those.*
226e0 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65 73 20  *     processes 
226f0 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a  uses nolock=1..*
22700 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d  *.**  <li> <b>im
22710 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68  mutable</b>: ^Th
22720 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 72 61  e immutable para
22730 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65  meter is a boole
22740 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20  an query.**     
22750 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69  parameter that i
22760 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68  ndicates that th
22770 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
22780 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20  is stored on.** 
22790 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65      read-only me
227a0 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75  dia.  ^When immu
227b0 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20 53 51  table is set, SQ
227c0 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
227d0 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61 74  t the.**     dat
227e0 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f  abase file canno
227f0 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20 65 76  t be changed, ev
22800 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73 73 20  en by a process 
22810 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a 20 20  with higher.**  
22820 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20 61 6e     privilege, an
22830 64 20 73 6f 20 74 68 65 20 64 61 74 61 62 61 73  d so the databas
22840 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65 61 64  e is opened read
22850 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f  -only and all lo
22860 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64  cking.**     and
22870 20 63 68 61 6e 67 65 20 64 65 74 65 63 74 69 6f   change detectio
22880 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20  n is disabled.  
22890 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67  Caution: Setting
228a0 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a   the immutable.*
228b0 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79 20 6f  *     property o
228c0 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
228d0 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e 20 66  e that does in f
228e0 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e 20 72  act change can r
228f0 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20  esult.**     in 
22900 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72 79 20  incorrect query 
22910 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b  results and/or [
22920 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 20  SQLITE_CORRUPT] 
22930 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53  errors..**     S
22940 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45  ee also: [SQLITE
22950 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45  _IOCAP_IMMUTABLE
22960 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20  ]..**       .** 
22970 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65  </ul>.**.** ^Spe
22980 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f  cifying an unkno
22990 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  wn parameter in 
229a0 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  the query compon
229b0 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 20  ent of a URI is 
229c0 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e  not an.** error.
229d0 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
229e0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
229f0 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64  t understand add
22a00 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a  itional query.**
22a10 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65   parameters.  Se
22a20 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65  e "[query parame
22a30 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69 61  ters with specia
22a40 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c  l meaning to SQL
22a50 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64  ite]" for.** add
22a60 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
22a70 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  ion..**.** [[URI
22a80 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c   filename exampl
22a90 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c  es]] <h3>URI fil
22aa0 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f  ename examples</
22ab0 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65  h3>.**.** <table
22ac0 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67   border="1" alig
22ad0 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64  n=center cellpad
22ae0 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c  ding=5>.** <tr><
22af0 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  th> URI filename
22b00 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a  s <th> Results.*
22b10 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
22b20 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a  data.db <td> .**
22b30 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74            Open t
22b40 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  he file "data.db
22b50 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  " in the current
22b60 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c   directory..** <
22b70 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f  tr><td> file:/ho
22b80 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c  me/fred/data.db<
22b90 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  br>.**          
22ba0 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65  file:///home/fre
22bb0 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a  d/data.db <br> .
22bc0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
22bd0 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d  ://localhost/hom
22be0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
22bf0 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  br> <td> .**    
22c00 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64        Open the d
22c10 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68  atabase file "/h
22c20 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
22c30 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  "..** <tr><td> f
22c40 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68  ile://darkstar/h
22c50 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
22c60 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
22c70 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61     An error. "da
22c80 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61  rkstar" is not a
22c90 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68   recognized auth
22ca0 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  ority..** <tr><t
22cb0 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73  d style="white-s
22cc0 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a  pace:nowrap"> .*
22cd0 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
22ce0 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25  ///C:/Documents%
22cf0 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73  20and%20Settings
22d00 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61  /fred/Desktop/da
22d10 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64  ta.db.**     <td
22d20 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20  > Windows only: 
22d30 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
22d40 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27  ata.db" on fred'
22d50 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69  s desktop on dri
22d60 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43  ve.**          C
22d70 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  :. Note that the
22d80 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e   %20 escaping in
22d90 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73   this example is
22da0 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a   not strictly .*
22db0 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 73  *          neces
22dc0 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 61  sary - space cha
22dd0 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 75  racters can be u
22de0 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a  sed literally.**
22df0 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 49            in URI
22e00 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c   filenames..** <
22e10 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
22e20 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63  a.db?mode=ro&cac
22e30 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20  he=private <td> 
22e40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
22e50 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  n file "data.db"
22e60 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
22e70 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65  directory for re
22e80 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a  ad-only access..
22e90 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 61  **          Rega
22ea0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
22eb0 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d  r or not shared-
22ec0 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e  cache mode is en
22ed0 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  abled by.**     
22ee0 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73       default, us
22ef0 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63 68  e a private cach
22f00 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  e..** <tr><td> f
22f10 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  ile:/home/fred/d
22f20 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d  ata.db?vfs=unix-
22f30 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20  dotfile <td>.** 
22f40 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69           Open fi
22f50 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
22f60 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65  ata.db". Use the
22f70 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e   special VFS "un
22f80 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20  ix-dotfile".**  
22f90 20 20 20 20 20 20 20 20 74 68 61 74 20 75 73 65          that use
22fa0 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70  s dot-files in p
22fb0 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20 61 64  lace of posix ad
22fc0 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a  visory locking..
22fd0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
22fe0 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65  :data.db?mode=re
22ff0 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20  adonly <td> .** 
23000 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f           An erro
23010 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73  r. "readonly" is
23020 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74   not a valid opt
23030 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64  ion for the "mod
23040 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  e" parameter..**
23050 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20   </table>.**.** 
23060 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c  ^URI hexadecimal
23070 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
23080 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70 70  s (%HH) are supp
23090 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68 65  orted within the
230a0 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65   path and.** que
230b0 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66  ry components of
230c0 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64 65   a URI. A hexade
230d0 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
230e0 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f  uence consists o
230f0 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73  f a.** percent s
23100 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c  ign - "%" - foll
23110 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79 20  owed by exactly 
23120 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20  two hexadecimal 
23130 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69  digits .** speci
23140 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76  fying an octet v
23150 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68  alue. ^Before th
23160 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79 20  e path or query 
23170 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a  components of a.
23180 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  ** URI filename 
23190 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c  are interpreted,
231a0 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65   they are encode
231b0 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e  d using UTF-8 an
231c0 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65  d all .** hexade
231d0 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
231e0 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20  uences replaced 
231f0 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65  by a single byte
23200 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a   containing the.
23210 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  ** corresponding
23220 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73 20   octet. If this 
23230 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65  process generate
23240 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46  s an invalid UTF
23250 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20  -8 encoding,.** 
23260 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
23270 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
23280 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
23290 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20  ows users:</b>  
232a0 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  The encoding use
232b0 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61  d for the filena
232c0 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f  me argument.** o
232d0 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  f sqlite3_open()
232e0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
232f0 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55  n_v2() must be U
23300 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76  TF-8, not whatev
23310 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69  er.** codepage i
23320 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  s currently defi
23330 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20  ned.  Filenames 
23340 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72  containing inter
23350 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72  national.** char
23360 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63  acters must be c
23370 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d  onverted to UTF-
23380 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69  8 prior to passi
23390 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20  ng them into.** 
233a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
233b0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
233c0 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  2()..**.** <b>No
233d0 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75  te to Windows Ru
233e0 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e  ntime users:</b>
233f0 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20    The temporary 
23400 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62  directory must b
23410 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74  e set.** prior t
23420 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65  o calling sqlite
23430 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
23440 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20  te3_open_v2().  
23450 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f  Otherwise, vario
23460 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74  us.** features t
23470 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65 20  hat require the 
23480 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79  use of temporary
23490 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e   files may fail.
234a0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
234b0 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64   [sqlite3_temp_d
234c0 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74  irectory].*/.int
234d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20   sqlite3_open(. 
234e0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
234f0 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
23500 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
23510 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
23520 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
23530 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
23540 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
23550 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  ;.int sqlite3_op
23560 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f  en16(.  const vo
23570 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  id *filename,   
23580 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
23590 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f  name (UTF-16) */
235a0 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
235b0 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
235c0 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
235d0 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  dle */.);.int sq
235e0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20  lite3_open_v2(. 
235f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
23600 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
23610 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
23620 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
23630 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20  e3 **ppDb,      
23640 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
23650 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  e db handle */. 
23660 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20   int flags,     
23670 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67           /* Flag
23680 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  s */.  const cha
23690 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f  r *zVfs        /
236a0 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f  * Name of VFS mo
236b0 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29  dule to use */.)
236c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
236d0 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73  F: Obtain Values
236e0 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74   For URI Paramet
236f0 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ers.**.** These 
23700 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74  are utility rout
23710 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20  ines, useful to 
23720 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
23730 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a  ons, that check.
23740 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64  ** to see if a d
23750 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73  atabase file was
23760 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74   a URI that cont
23770 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63  ained a specific
23780 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d   query .** param
23790 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20  eter, and if so 
237a0 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75  obtains the valu
237b0 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 20  e of that query 
237c0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
237d0 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61 74   If F is the dat
237e0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70  abase filename p
237f0 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e  ointer passed in
23800 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d  to the xOpen() m
23810 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56  ethod of .** a V
23820 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
23830 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73  n when the flags
23840 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
23850 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72  pen() has one or
23860 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65   .** more of the
23870 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
23880 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  I] or [SQLITE_OP
23890 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73  EN_MAIN_DB] bits
238a0 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73   set and.** P is
238b0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
238c0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
238d0 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
238e0 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
238f0 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 65  F,P) returns the
23900 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a   value of the P.
23910 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20  ** parameter if 
23920 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e  it exists or a N
23930 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50  ULL pointer if P
23940 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72   does not appear
23950 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20   as a .** query 
23960 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20  parameter on F. 
23970 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72 79   If P is a query
23980 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a   parameter of F.
23990 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63  ** has no explic
239a0 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73  it value, then s
239b0 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
239c0 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
239d0 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
239e0 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  o an empty strin
239f0 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  g..**.** The sql
23a00 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
23a10 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20  (F,P,B) routine 
23a20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 69  assumes that P i
23a30 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70  s a boolean.** p
23a40 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
23a50 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72  urns true (1) or
23a60 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72   false (0) accor
23a70 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75  ding to the valu
23a80 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20  e.** of P.  The 
23a90 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
23aa0 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
23ab0 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ne returns true 
23ac0 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61  (1) if the.** va
23ad0 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 72  lue of query par
23ae0 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20  ameter P is one 
23af0 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 22  of "yes", "true"
23b00 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79  , or "on" in any
23b10 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74  .** case or if t
23b20 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20  he value begins 
23b30 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  with a non-zero 
23b40 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a  number.  The .**
23b50 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
23b60 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
23b70 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c  ines returns fal
23b80 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76 61  se (0) if the va
23b90 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20  lue of.** query 
23ba0 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f  parameter P is o
23bb0 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c  ne of "no", "fal
23bc0 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e  se", or "off" in
23bd0 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20   any case or.** 
23be0 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67  if the value beg
23bf0 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72  ins with a numer
23c00 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69  ic zero.  If P i
23c10 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a  s not a query.**
23c20 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20   parameter on F 
23c30 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  or if the value 
23c40 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74  of P is does not
23c50 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68   match any of th
23c60 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e  e.** above, then
23c70 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
23c80 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75  lean(F,P,B) retu
23c90 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a  rns (B!=0)..**.*
23ca0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72  * The sqlite3_ur
23cb0 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72  i_int64(F,P,D) r
23cc0 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20  outine converts 
23cd0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
23ce0 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20  nto a.** 64-bit 
23cf0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61  signed integer a
23d00 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 20  nd returns that 
23d10 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66  integer, or D if
23d20 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65   P does not.** e
23d30 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 61  xist.  If the va
23d40 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65  lue of P is some
23d50 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
23d60 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65   an integer, the
23d70 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74  n.** zero is ret
23d80 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66  urned..** .** If
23d90 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   F is a NULL poi
23da0 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74  nter, then sqlit
23db0 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
23dc0 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55  (F,P) returns NU
23dd0 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  LL and.** sqlite
23de0 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
23df0 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20  P,B) returns B. 
23e00 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e   If F is not a N
23e10 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a  ULL pointer and.
23e20 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  ** is not a data
23e30 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61  base file pathna
23e40 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  me pointer that 
23e50 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e  SQLite passed in
23e60 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20  to the xOpen.** 
23e70 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e  VFS method, then
23e80 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
23e90 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
23ea0 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
23eb0 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73  robably.** undes
23ec0 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74  irable..*/.const
23ed0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75   char *sqlite3_u
23ee0 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e  ri_parameter(con
23ef0 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
23f00 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  me, const char *
23f10 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c  zParam);.int sql
23f20 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
23f30 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69  (const char *zFi
23f40 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  le, const char *
23f50 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66  zParam, int bDef
23f60 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69  ault);.sqlite3_i
23f70 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69  nt64 sqlite3_uri
23f80 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61  _int64(const cha
23f90 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  r*, const char*,
23fa0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
23fb0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
23fc0 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41  F: Error Codes A
23fd0 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a  nd Messages.**.*
23fe0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
23ff0 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61  rrcode() interfa
24000 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
24010 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63  umeric [result c
24020 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  ode] or.** [exte
24030 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
24040 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72  ] for the most r
24050 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c  ecent failed sql
24060 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a  ite3_* API call.
24070 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
24080 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
24090 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61  onnection]. If a
240a0 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20   prior API call 
240b0 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68  failed.** but th
240c0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50  e most recent AP
240d0 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64  I call succeeded
240e0 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
240f0 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74  ue from.** sqlit
24100 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20  e3_errcode() is 
24110 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65  undefined.  ^The
24120 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
24130 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69  d_errcode().** i
24140 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20  nterface is the 
24150 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74  same except that
24160 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72   it always retur
24170 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65  ns the .** [exte
24180 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
24190 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65  ] even when exte
241a0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
241b0 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65  s are.** disable
241c0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
241d0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61  lite3_errmsg() a
241e0 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  nd sqlite3_errms
241f0 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67  g16() return Eng
24200 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a  lish-language.**
24210 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72   text that descr
24220 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20  ibes the error, 
24230 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
24240 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63  or UTF-16 respec
24250 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d  tively..** ^(Mem
24260 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
24270 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
24280 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
24290 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54  internally..** T
242a0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
242b0 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
242c0 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65  worry about free
242d0 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a  ing the result..
242e0 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
242f0 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67  error string mig
24300 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65  ht be overwritte
24310 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64  n or deallocated
24320 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e   by.** subsequen
24330 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72  t calls to other
24340 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
24350 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a  e functions.)^.*
24360 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
24370 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65 72  3_errstr() inter
24380 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
24390 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
243a0 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64  e text.** that d
243b0 65 73 63 72 69 62 65 73 20 74 68 65 20 5b 72 65  escribes the [re
243c0 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55  sult code], as U
243d0 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72  TF-8..** ^(Memor
243e0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72  y to hold the er
243f0 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
24400 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e  ng is managed in
24410 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20  ternally.** and 
24420 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65  must not be free
24430 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
24440 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68  tion)^..**.** Wh
24450 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  en the serialize
24460 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
24470 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74  e] is in use, it
24480 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a   might be the.**
24490 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63   case that a sec
244a0 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ond error occurs
244b0 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74   on a separate t
244c0 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e  hread in between
244d0 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20  .** the time of 
244e0 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20  the first error 
244f0 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20  and the call to 
24500 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
24510 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68  ..** When that h
24520 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f  appens, the seco
24530 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65  nd error will be
24540 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20   reported since 
24550 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61  these.** interfa
24560 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72  ces always repor
24570 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
24580 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76  t result.  To av
24590 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63  oid.** this, eac
245a0 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74  h thread can obt
245b0 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73  ain exclusive us
245c0 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  e of the [databa
245d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
245e0 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20  .** by invoking 
245f0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65  [sqlite3_mutex_e
24600 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64  nter]([sqlite3_d
24610 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66  b_mutex](D)) bef
24620 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a  ore beginning.**
24630 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e   to use D and in
24640 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
24650 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71  mutex_leave]([sq
24660 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
24670 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c  D)) after.** all
24680 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e   calls to the in
24690 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20  terfaces listed 
246a0 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74  here are complet
246b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ed..**.** If an 
246c0 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20  interface fails 
246d0 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55  with SQLITE_MISU
246e0 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  SE, that means t
246f0 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
24700 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f  was invoked inco
24710 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61  rrectly by the a
24720 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20  pplication.  In 
24730 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a  that case, the.*
24740 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64  * error code and
24750 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20   message may or 
24760 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a  may not be set..
24770 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
24780 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
24790 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  db);.int sqlite3
247a0 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
247b0 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
247c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
247d0 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74  te3_errmsg(sqlit
247e0 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  e3*);.const void
247f0 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
24800 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f  16(sqlite3*);.co
24810 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
24820 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a  3_errstr(int);..
24830 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24840 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  SQL Statement Ob
24850 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
24860 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  : {prepared stat
24870 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64  ement} {prepared
24880 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a   statements}.**.
24890 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
248a0 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65  f this object re
248b0 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c  presents a singl
248c0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
248d0 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
248e0 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f  is variously kno
248f0 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65  wn as a "prepare
24900 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  d statement" or 
24910 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53  a.** "compiled S
24920 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  QL statement" or
24930 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74   simply as a "st
24940 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20  atement"..**.** 
24950 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74  The life of a st
24960 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67  atement object g
24970 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69  oes something li
24980 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
24990 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61  ol>.** <li> Crea
249a0 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  te the object us
249b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
249c0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20  pare_v2()] or a 
249d0 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  related.**      
249e0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69  function..** <li
249f0 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  > Bind values to
24a00 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   [host parameter
24a10 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  s] using the sql
24a20 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a  ite3_bind_*().**
24a30 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
24a40 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68  ..** <li> Run th
24a50 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67  e SQL by calling
24a60 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
24a70 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  ] one or more ti
24a80 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73  mes..** <li> Res
24a90 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  et the statement
24aa0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
24ab0 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f  reset()] then go
24ac0 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f   back.**      to
24ad0 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69   step 2.  Do thi
24ae0 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74  s zero or more t
24af0 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65  imes..** <li> De
24b00 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74  stroy the object
24b10 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
24b20 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20  finalize()]..** 
24b30 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65  </ol>.**.** Refe
24b40 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69  r to documentati
24b50 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
24b60 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66   methods above f
24b70 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
24b80 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
24b90 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24ba0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c  sqlite3_stmt sql
24bb0 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a  ite3_stmt;../*.*
24bc0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
24bd0 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a  time Limits.**.*
24be0 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61  * ^(This interfa
24bf0 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69  ce allows the si
24c00 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f  ze of various co
24c10 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c  nstructs to be l
24c20 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63  imited.** on a c
24c30 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e  onnection by con
24c40 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20  nection basis.  
24c50 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
24c60 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64  ter is the.** [d
24c70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24c80 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20  on] whose limit 
24c90 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20  is to be set or 
24ca0 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a  queried.  The.**
24cb0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
24cc0 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  r is one of the 
24cd0 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  [limit categorie
24ce0 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  s] that define a
24cf0 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e  .** class of con
24d00 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69  structs to be si
24d10 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65  ze limited.  The
24d20 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
24d30 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c   is the.** new l
24d40 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f  imit for that co
24d50 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a  nstruct.)^.**.**
24d60 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d   ^If the new lim
24d70 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65  it is a negative
24d80 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d   number, the lim
24d90 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e  it is unchanged.
24da0 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c  .** ^(For each l
24db0 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51  imit category SQ
24dc0 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41  LITE_LIMIT_<i>NA
24dd0 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20  ME</i> there is 
24de0 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  a .** [limits | 
24df0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
24e00 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70  ].** set at comp
24e10 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20  ile-time by a C 
24e20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
24e30 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69  ro called.** [li
24e40 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41  mits | SQLITE_MA
24e50 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a  X_<i>NAME</i>]..
24e60 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f  ** (The "_LIMIT_
24e70 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73  " in the name is
24e80 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41   changed to "_MA
24e90 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65  X_".))^.** ^Atte
24ea0 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65  mpts to increase
24eb0 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69   a limit above i
24ec0 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  ts hard upper bo
24ed0 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e  und are.** silen
24ee0 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f  tly truncated to
24ef0 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20   the hard upper 
24f00 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65  bound..**.** ^Re
24f10 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
24f20 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c  her or not the l
24f30 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64  imit was changed
24f40 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  , the .** [sqlit
24f50 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65  e3_limit()] inte
24f60 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
24f70 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
24f80 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e   the limit..** ^
24f90 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74  Hence, to find t
24fa0 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
24fb0 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68   of a limit with
24fc0 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c  out changing it,
24fd0 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b  .** simply invok
24fe0 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  e this interface
24ff0 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20   with the third 
25000 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f  parameter set to
25010 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74   -1..**.** Run-t
25020 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69  ime limits are i
25030 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
25040 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  in applications 
25050 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62  that manage.** b
25060 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e  oth their own in
25070 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20  ternal database 
25080 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73  and also databas
25090 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74  es that are cont
250a0 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74  rolled.** by unt
250b0 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20  rusted external 
250c0 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61  sources.  An exa
250d0 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  mple application
250e0 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77   might be a.** w
250f0 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20  eb browser that 
25100 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61  has its own data
25110 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e  bases for storin
25120 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a  g history and.**
25130 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61   separate databa
25140 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62  ses controlled b
25150 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70  y JavaScript app
25160 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f  lications downlo
25170 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20  aded.** off the 
25180 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69  Internet.  The i
25190 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
251a0 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74  s can be given t
251b0 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66  he.** large, def
251c0 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61  ault limits.  Da
251d0 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20  tabases managed 
251e0 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  by external sour
251f0 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69  ces can.** be gi
25200 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72  ven much smaller
25210 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64   limits designed
25220 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65   to prevent a de
25230 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a  nial of service.
25240 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65  ** attack.  Deve
25250 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73  lopers might als
25260 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68  o want to use th
25270 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
25280 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20  uthorizer()].** 
25290 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72  interface to fur
252a0 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74  ther control unt
252b0 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65  rusted SQL.  The
252c0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74   size of the dat
252d0 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64  abase.** created
252e0 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64   by an untrusted
252f0 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63   script can be c
25300 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74  ontained using t
25310 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f  he.** [max_page_
25320 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e  count] [PRAGMA].
25330 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74  .**.** New run-t
25340 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ime limit catego
25350 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  ries may be adde
25360 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
25370 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ases..*/.int sql
25380 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74  ite3_limit(sqlit
25390 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74  e3*, int id, int
253a0 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a   newVal);../*.**
253b0 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
253c0 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f  ime Limit Catego
253d0 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ries.** KEYWORDS
253e0 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  : {limit categor
253f0 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67  y} {*limit categ
25400 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  ories}.**.** The
25410 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  se constants def
25420 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66  ine various perf
25430 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a  ormance limits.*
25440 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f  * that can be lo
25450 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d  wered at run-tim
25460 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  e using [sqlite3
25470 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68  _limit()]..** Th
25480 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68  e synopsis of th
25490 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68  e meanings of th
254a0 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73  e various limits
254b0 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e   is shown below.
254c0 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69  .** Additional i
254d0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76  nformation is av
254e0 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69  ailable at [limi
254f0 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53  ts | Limits in S
25500 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64  QLite]..**.** <d
25510 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  l>.** [[SQLITE_L
25520 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28  IMIT_LENGTH]] ^(
25530 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
25540 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
25550 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
25560 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69  size of any stri
25570 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61  ng or BLOB or ta
25580 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65  ble row, in byte
25590 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  s.<dd>)^.**.** [
255a0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51  [SQLITE_LIMIT_SQ
255b0 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74  L_LENGTH]] ^(<dt
255c0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51  >SQLITE_LIMIT_SQ
255d0 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  L_LENGTH</dt>.**
255e0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
255f0 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51   length of an SQ
25600 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20  L statement, in 
25610 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  bytes.</dd>)^.**
25620 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
25630 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64  IT_COLUMN]] ^(<d
25640 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
25650 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  OLUMN</dt>.** <d
25660 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
25670 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
25680 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e  in a table defin
25690 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a  ition or in the.
256a0 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ** result set of
256b0 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74   a [SELECT] or t
256c0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
256d0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
256e0 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69  an index.** or i
256f0 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72  n an ORDER BY or
25700 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65   GROUP BY clause
25710 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
25720 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58  [SQLITE_LIMIT_EX
25730 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74  PR_DEPTH]] ^(<dt
25740 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58  >SQLITE_LIMIT_EX
25750 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  PR_DEPTH</dt>.**
25760 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
25770 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61   depth of the pa
25780 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20  rse tree on any 
25790 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e  expression.</dd>
257a0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
257b0 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
257c0 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e  _SELECT]] ^(<dt>
257d0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
257e0 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74  POUND_SELECT</dt
257f0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
25800 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
25810 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75  erms in a compou
25820 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  nd SELECT statem
25830 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ent.</dd>)^.**.*
25840 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
25850 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74  _VDBE_OP]] ^(<dt
25860 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  >SQLITE_LIMIT_VD
25870 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  BE_OP</dt>.** <d
25880 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
25890 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74  mber of instruct
258a0 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61  ions in a virtua
258b0 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61  l machine progra
258c0 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70  m.** used to imp
258d0 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74  lement an SQL st
258e0 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c  atement.  This l
258f0 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72  imit is not curr
25900 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65  ently.** enforce
25910 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d  d, though that m
25920 69 67 68 74 20 62 65 20 61 64 64 65 64 20 69 6e  ight be added in
25930 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c   some future rel
25940 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74  ease of.** SQLit
25950 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  e.</dd>)^.**.** 
25960 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  [[SQLITE_LIMIT_F
25970 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28  UNCTION_ARG]] ^(
25980 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
25990 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64  _FUNCTION_ARG</d
259a0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
259b0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
259c0 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66  arguments on a f
259d0 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  unction.</dd>)^.
259e0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
259f0 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20  IMIT_ATTACHED]] 
25a00 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
25a10 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e  IT_ATTACHED</dt>
25a20 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
25a30 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41  mum number of [A
25a40 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64  TTACH | attached
25a50 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f   databases].)^</
25a60 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
25a70 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
25a80 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a  TTERN_LENGTH]].*
25a90 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
25aa0 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
25ab0 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  N_LENGTH</dt>.**
25ac0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
25ad0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70   length of the p
25ae0 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20  attern argument 
25af0 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72  to the [LIKE] or
25b00 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61  .** [GLOB] opera
25b10 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  tors.</dd>)^.**.
25b20 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
25b30 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
25b40 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  R]].** ^(<dt>SQL
25b50 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
25b60 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a  LE_NUMBER</dt>.*
25b70 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
25b80 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f  m index number o
25b90 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72  f any [parameter
25ba0 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  ] in an SQL stat
25bb0 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  ement.)^.**.** [
25bc0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  [SQLITE_LIMIT_TR
25bd0 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28  IGGER_DEPTH]] ^(
25be0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
25bf0 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f  _TRIGGER_DEPTH</
25c00 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
25c10 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
25c20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72  recursion for tr
25c30 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a  iggers.</dd>)^.*
25c40 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
25c50 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41  MIT_WORKER_THREA
25c60 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  DS]] ^(<dt>SQLIT
25c70 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54  E_LIMIT_WORKER_T
25c80 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c  HREADS</dt>.** <
25c90 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
25ca0 75 6d 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61  umber of auxilia
25cb0 72 79 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64  ry worker thread
25cc0 73 20 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a  s that a single.
25cd0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
25ce0 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72  tement] may star
25cf0 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  t.</dd>)^.** </d
25d00 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
25d10 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
25d20 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
25d30 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
25d40 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
25d50 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
25d60 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
25d70 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
25d80 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  UMN             
25d90 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
25da0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58   SQLITE_LIMIT_EX
25db0 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  PR_DEPTH        
25dc0 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
25dd0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
25de0 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20  OMPOUND_SELECT  
25df0 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
25e00 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
25e10 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20  VDBE_OP         
25e20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
25e30 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
25e40 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20  _FUNCTION_ARG   
25e50 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
25e60 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
25e70 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20  T_ATTACHED      
25e80 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
25e90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
25ea0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
25eb0 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23  LENGTH       8.#
25ec0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
25ed0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
25ee0 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a  BER           9.
25ef0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
25f00 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
25f10 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30  TH            10
25f20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
25f30 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52  LIMIT_WORKER_THR
25f40 45 41 44 53 20 20 20 20 20 20 20 20 20 20 20 31  EADS           1
25f50 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  1../*.** CAPI3RE
25f60 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20  F: Compiling An 
25f70 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL Statement.**
25f80 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
25f90 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c  statement compil
25fa0 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65  er}.**.** To exe
25fb0 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72  cute an SQL quer
25fc0 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74  y, it must first
25fd0 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74   be compiled int
25fe0 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a  o a byte-code.**
25ff0 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f   program using o
26000 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ne of these rout
26010 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ines..**.** The 
26020 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20  first argument, 
26030 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61  "db", is a [data
26040 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
26050 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
26060 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73  .** prior succes
26070 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
26080 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
26090 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
260a0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
260b0 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68  3_open16()].  Th
260c0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
260d0 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68  ction must not h
260e0 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e  ave been closed.
260f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
26100 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71  d argument, "zSq
26110 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65  l", is the state
26120 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
26130 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20  led, encoded.** 
26140 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
26150 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20  or UTF-16.  The 
26160 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
26170 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
26180 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e  epare_v2().** in
26190 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46  terfaces use UTF
261a0 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  -8, and sqlite3_
261b0 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20  prepare16() and 
261c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
261d0 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54  6_v2().** use UT
261e0 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  F-16..**.** ^If 
261f0 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65  the nByte argume
26200 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  nt is less than 
26210 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20  zero, then zSql 
26220 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68  is read up to th
26230 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20  e.** first zero 
26240 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20  terminator. ^If 
26250 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67  nByte is non-neg
26260 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69  ative, then it i
26270 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
26280 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65   number of  byte
26290 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
262a0 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69  .  ^When nByte i
262b0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
262c0 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69  the.** zSql stri
262d0 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65  ng ends at eithe
262e0 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30  r the first '\00
262f0 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63  0' or '\u0000' c
26300 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74  haracter or.** t
26310 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65  he nByte-th byte
26320 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65  , whichever come
26330 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20  s first. If the 
26340 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20  caller knows.** 
26350 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65  that the supplie
26360 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d  d string is nul-
26370 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e  terminated, then
26380 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c   there is a smal
26390 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65  l.** performance
263a0 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65   advantage to be
263b0 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69   gained by passi
263c0 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61  ng an nByte para
263d0 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73  meter that.** is
263e0 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75   equal to the nu
263f0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
26400 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
26410 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f  g <i>including</
26420 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65  i>.** the nul-te
26430 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20 61  rminator bytes a
26440 73 20 74 68 69 73 20 73 61 76 65 73 20 53 51 4c  s this saves SQL
26450 69 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 20  ite from having 
26460 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70  to.** make a cop
26470 79 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20 73  y of the input s
26480 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  tring..**.** ^If
26490 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e   pzTail is not N
264a0 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c  ULL then *pzTail
264b0 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
264c0 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62  t to the first b
264d0 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20  yte.** past the 
264e0 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74  end of the first
264f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
26500 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72  n zSql.  These r
26510 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20  outines only.** 
26520 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73  compile the firs
26530 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  t statement in z
26540 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20  Sql, so *pzTail 
26550 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
26560 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61   to.** what rema
26570 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a  ins uncompiled..
26580 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69  **.** ^*ppStmt i
26590 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
265a0 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70  to a compiled [p
265b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
265c0 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a  t] that can be.*
265d0 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67  * executed using
265e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
265f0 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73  ].  ^If there is
26600 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74   an error, *ppSt
26610 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20  mt is set.** to 
26620 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69  NULL.  ^If the i
26630 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69  nput text contai
26640 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68  ns no SQL (if th
26650 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d  e input is an em
26660 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72  pty.** string or
26670 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e   a comment) then
26680 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20   *ppStmt is set 
26690 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20  to NULL..** The 
266a0 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72  calling procedur
266b0 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  e is responsible
266c0 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68   for deleting th
266d0 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51  e compiled.** SQ
266e0 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  L statement usin
266f0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
26700 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20  ize()] after it 
26710 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
26720 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20  h it..** ppStmt 
26730 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e  may not be NULL.
26740 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65  .**.** ^On succe
26750 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ss, the sqlite3_
26760 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79  prepare() family
26770 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74   of routines ret
26780 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b  urn [SQLITE_OK];
26790 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e  .** otherwise an
267a0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
267b0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
267c0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
267d0 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71  pare_v2() and sq
267e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
267f0 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20  v2() interfaces 
26800 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64  are.** recommend
26810 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70  ed for all new p
26820 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f  rograms. The two
26830 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65   older interface
26840 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a  s are retained.*
26850 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  * for backwards 
26860 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62  compatibility, b
26870 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20  ut their use is 
26880 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20  discouraged..** 
26890 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
268a0 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65  erfaces, the pre
268b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
268c0 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72  ** that is retur
268d0 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ned (the [sqlite
268e0 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20  3_stmt] object) 
268f0 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20  contains a copy 
26900 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  of the.** origin
26910 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69  al SQL text. Thi
26920 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71  s causes the [sq
26930 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e  lite3_step()] in
26940 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65  terface to.** be
26950 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79  have differently
26960 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a   in three ways:.
26970 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
26980 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  i>.** ^If the da
26990 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
269a0 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f  anges, instead o
269b0 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  f returning [SQL
269c0 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69  ITE_SCHEMA] as i
269d0 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64  t.** always used
269e0 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33   to do, [sqlite3
269f0 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75  _step()] will au
26a00 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
26a10 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a  mpile the SQL.**
26a20 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
26a30 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61  ry to run it aga
26a40 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b  in. As many as [
26a50 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d  SQLITE_MAX_SCHEM
26a60 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72  A_RETRY].** retr
26a70 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62  ies will occur b
26a80 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74  efore sqlite3_st
26a90 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e  ep() gives up an
26aa0 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72  d returns an err
26ab0 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  or..** </li>.**.
26ac0 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e  ** <li>.** ^When
26ad0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
26ae0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
26af0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f  )] will return o
26b00 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c  ne of the detail
26b10 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  ed.** [error cod
26b20 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  es] or [extended
26b30 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20   error codes].  
26b40 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61  ^The legacy beha
26b50 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a  vior was that.**
26b60 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
26b70 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74  ] would only ret
26b80 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53  urn a generic [S
26b90 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73  QLITE_ERROR] res
26ba0 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20  ult code.** and 
26bb0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
26bc0 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61  would have to ma
26bd0 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ke a second call
26be0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
26bf0 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65  et()].** in orde
26c00 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e  r to find the un
26c10 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f  derlying cause o
26c20 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57  f the problem. W
26c30 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65  ith the "v2" pre
26c40 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  pare.** interfac
26c50 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69  es, the underlyi
26c60 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68  ng reason for th
26c70 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  e error is retur
26c80 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  ned immediately.
26c90 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
26ca0 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
26cb0 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62  specific value b
26cc0 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74  ound to [paramet
26cd0 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65  er | host parame
26ce0 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20  ter] in the .** 
26cf0 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67  WHERE clause mig
26d00 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
26d10 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
26d20 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74   plan for a stat
26d30 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74  ement,.** then t
26d40 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c  he statement wil
26d50 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
26d60 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61  ly recompiled, a
26d70 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62  s if there had b
26d80 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61  een .** a schema
26d90 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20   change, on the 
26da0 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f  first  [sqlite3_
26db0 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c  step()] call fol
26dc0 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67  lowing any chang
26dd0 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  e.** to the [sql
26de0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
26df0 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68   bindings] of th
26e00 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20  at [parameter]. 
26e10 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69  .** ^The specifi
26e20 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45  c value of WHERE
26e30 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74  -clause [paramet
26e40 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  er] might influe
26e50 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69  nce the .** choi
26e60 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
26e70 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
26e80 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61  r is the left-ha
26e90 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49  nd side of a [LI
26ea0 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d  KE].** or [GLOB]
26eb0 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20   operator or if 
26ec0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
26ed0 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20   compared to an 
26ee0 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a  indexed column.*
26ef0 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54  * and the [SQLIT
26f00 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20  E_ENABLE_STAT3] 
26f10 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
26f20 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
26f30 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c  ** </li>.** </ol
26f40 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  >.*/.int sqlite3
26f50 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69  _prepare(.  sqli
26f60 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
26f70 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
26f80 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
26f90 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
26fa0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
26fb0 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
26fc0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
26fd0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
26fe0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
26ff0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
27000 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
27010 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
27020 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
27030 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
27040 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
27050 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
27060 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
27070 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
27080 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
27090 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a  te3_prepare_v2(.
270a0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
270b0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
270c0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
270d0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
270e0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
270f0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
27100 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
27110 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
27120 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
27130 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
27140 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
27150 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
27160 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
27170 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
27180 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
27190 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
271a0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
271b0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
271c0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
271d0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
271e0 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  e16(.  sqlite3 *
271f0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
27200 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
27210 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
27220 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
27230 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
27240 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
27250 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
27260 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
27270 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
27280 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
27290 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
272a0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
272b0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
272c0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
272d0 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
272e0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
272f0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
27300 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
27310 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
27320 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20  prepare16_v2(.  
27330 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
27340 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
27350 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
27360 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
27370 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
27380 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
27390 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
273a0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
273b0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
273c0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
273d0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
273e0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
273f0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
27400 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
27410 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
27420 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
27430 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
27440 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
27450 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a  f zSql */.);../*
27460 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
27470 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65  trieving Stateme
27480 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68  nt SQL.**.** ^Th
27490 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
274a0 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72   be used to retr
274b0 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70  ieve a saved cop
274c0 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61  y of the origina
274d0 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73  l.** SQL text us
274e0 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b  ed to create a [
274f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27500 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74  nt] if that stat
27510 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d  ement was.** com
27520 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68  piled using eith
27530 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
27540 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
27550 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
27560 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  v2()]..*/.const 
27570 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71  char *sqlite3_sq
27580 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  l(sqlite3_stmt *
27590 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
275a0 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
275b0 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
275c0 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68  tement Writes Th
275d0 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a  e Database.**.**
275e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
275f0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69  mt_readonly(X) i
27600 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
27610 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29   true (non-zero)
27620 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20   if.** and only 
27630 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  if the [prepared
27640 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61   statement] X ma
27650 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68  kes no direct ch
27660 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20  anges to.** the 
27670 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64  content of the d
27680 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a  atabase file..**
27690 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61  .** Note that [a
276a0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
276b0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
276c0 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c  ] or.** [virtual
276d0 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63   tables] might c
276e0 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
276f0 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73  se indirectly as
27700 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e 20   a side effect. 
27710 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70   .** ^(For examp
27720 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63  le, if an applic
27730 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20  ation defines a 
27740 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29  function "eval()
27750 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73  " that .** calls
27760 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
27770 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c  ], then the foll
27780 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  owing SQL statem
27790 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61  ent would.** cha
277a0 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
277b0 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69   file through si
277c0 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a  de-effects:.**.*
277d0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
277e0 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54  re>.**    SELECT
277f0 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52   eval('DELETE FR
27800 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b  OM t1') FROM t2;
27810 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
27820 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75  kquote>.**.** Bu
27830 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b 53  t because the [S
27840 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
27850 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
27860 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
27870 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20  le.** directly, 
27880 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
27890 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74  donly() would st
278a0 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e  ill return true.
278b0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61  )^.**.** ^Transa
278c0 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74  ction control st
278d0 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73  atements such as
278e0 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49   [BEGIN], [COMMI
278f0 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a  T], [ROLLBACK],.
27900 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20  ** [SAVEPOINT], 
27910 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61  and [RELEASE] ca
27920 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  use sqlite3_stmt
27930 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72  _readonly() to r
27940 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73  eturn true,.** s
27950 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d 65  ince the stateme
27960 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64  nts themselves d
27970 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d  o not actually m
27980 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61  odify the databa
27990 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72  se but.** rather
279a0 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68   they control th
279b0 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e  e timing of when
279c0 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74   other statement
279d0 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a  s modify the .**
279e0 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65   database.  ^The
279f0 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44   [ATTACH] and [D
27a00 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74  ETACH] statement
27a10 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20  s also cause.** 
27a20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
27a30 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72  donly() to retur
27a40 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68  n true since, wh
27a50 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d  ile those statem
27a60 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ents.** change t
27a70 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
27a80 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 63   of a database c
27a90 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20  onnection, they 
27aa0 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20  do not make .** 
27ab0 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63  changes to the c
27ac0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61  ontent of the da
27ad0 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20  tabase files on 
27ae0 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  disk..*/.int sql
27af0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
27b00 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ly(sqlite3_stmt 
27b10 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
27b20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
27b30 69 6e 65 20 49 66 20 41 20 50 72 65 70 61 72 65  ine If A Prepare
27b40 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20  d Statement Has 
27b50 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a 2a  Been Reset.**.**
27b60 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
27b70 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72  mt_busy(S) inter
27b80 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75  face returns tru
27b90 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20  e (non-zero) if 
27ba0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
27bb0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61   statement] S ha
27bc0 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 61  s been stepped a
27bd0 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69  t least once usi
27be0 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
27bf0 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 73  step(S)] but has
27c00 20 6e 6f 74 20 72 75 6e 20 74 6f 20 63 6f 6d 70   not run to comp
27c10 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f 72 20 68 61  letion and/or ha
27c20 73 20 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e 20 72  s not .** been r
27c30 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  eset using [sqli
27c40 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20  te3_reset(S)].  
27c50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
27c60 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74  t_busy(S).** int
27c70 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 66  erface returns f
27c80 61 6c 73 65 20 69 66 20 53 20 69 73 20 61 20 4e  alse if S is a N
27c90 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66  ULL pointer.  If
27ca0 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20   S is not a .** 
27cb0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64  NULL pointer and
27cc0 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65   is not a pointe
27cd0 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72  r to a valid [pr
27ce0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27cf0 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65  ].** object, the
27d00 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
27d10 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
27d20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72  probably undesir
27d30 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  able..**.** This
27d40 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
27d50 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e  e used in combin
27d60 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e  ation [sqlite3_n
27d70 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74  ext_stmt()].** t
27d80 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65  o locate all pre
27d90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
27da0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
27db0 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20   a database .** 
27dc0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
27dd0 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62  are in need of b
27de0 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69  eing reset.  Thi
27df0 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a  s can be used,.*
27e00 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  * for example, i
27e10 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75  n diagnostic rou
27e20 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20  tines to search 
27e30 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a  for prepared .**
27e40 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
27e50 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74   are holding a t
27e60 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e  ransaction open.
27e70 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
27e80 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65  stmt_busy(sqlite
27e90 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
27ea0 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d   CAPI3REF: Dynam
27eb0 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c  ically Typed Val
27ec0 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  ue Object.** KEY
27ed0 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65  WORDS: {protecte
27ee0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
27ef0 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   {unprotected sq
27f00 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a  lite3_value}.**.
27f10 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74  ** SQLite uses t
27f20 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
27f30 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65   object to repre
27f40 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a  sent all values.
27f50 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73  ** that can be s
27f60 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62  tored in a datab
27f70 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74  ase table. SQLit
27f80 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74  e uses dynamic t
27f90 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65  yping.** for the
27fa0 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65   values it store
27fb0 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72  s.  ^Values stor
27fc0 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61  ed in sqlite3_va
27fd0 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63  lue objects.** c
27fe0 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20  an be integers, 
27ff0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
28000 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20  alues, strings, 
28010 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a  BLOBs, or NULL..
28020 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33  **.** An sqlite3
28030 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61  _value object ma
28040 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f  y be either "pro
28050 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72  tected" or "unpr
28060 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d  otected"..** Som
28070 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  e interfaces req
28080 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64  uire a protected
28090 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20   sqlite3_value. 
280a0 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   Other interface
280b0 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74  s.** will accept
280c0 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63   either a protec
280d0 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ted or an unprot
280e0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
280f0 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e  lue..** Every in
28100 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63  terface that acc
28110 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c  epts sqlite3_val
28120 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65  ue arguments spe
28130 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65  cifies.** whethe
28140 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75  r or not it requ
28150 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64  ires a protected
28160 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
28170 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20  **.** The terms 
28180 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20  "protected" and 
28190 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65  "unprotected" re
281a0 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f  fer to whether o
281b0 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78  r not.** a mutex
281c0 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e   is held.  An in
281d0 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20  ternal mutex is 
281e0 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65  held for a prote
281f0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
28200 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74  value object but
28210 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c   no mutex is hel
28220 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  d for an unprote
28230 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
28240 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49  value object.  I
28250 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
28260 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c  iled to be singl
28270 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77  e-threaded.** (w
28280 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  ith [SQLITE_THRE
28290 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69  ADSAFE=0] and wi
282a0 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65  th [sqlite3_thre
282b0 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e  adsafe()] return
282c0 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20  ing 0).** or if 
282d0 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e  SQLite is run in
282e0 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20   one of reduced 
282f0 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20  mutex modes .** 
28300 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
28310 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20  INGLETHREAD] or 
28320 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
28330 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74  ULTITHREAD].** t
28340 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20  hen there is no 
28350 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
28360 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
28370 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
28380 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
28390 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20  bjects and they 
283a0 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65  can be used inte
283b0 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f  rchangeably.  Ho
283c0 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61  wever,.** for ma
283d0 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61  ximum code porta
283e0 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63  bility it is rec
283f0 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
28400 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74  plications.** st
28410 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73  ill make the dis
28420 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
28430 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
28440 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
28450 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
28460 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f  cts even when no
28470 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69  t strictly requi
28480 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  red..**.** ^The 
28490 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
284a0 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70  jects that are p
284b0 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74  assed as paramet
284c0 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ers into the.** 
284d0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
284e0 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  f [application-d
284f0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
28500 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63  ions] are protec
28510 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ted..** ^The sql
28520 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
28530 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
28540 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
28550 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70  _value()] is unp
28560 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70  rotected..** Unp
28570 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
28580 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d  _value objects m
28590 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
285a0 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  with.** [sqlite3
285b0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
285c0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
285d0 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  nd_value()]..** 
285e0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
285f0 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  ue_blob | sqlite
28600 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20  3_value_type()] 
28610 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74  family of.** int
28620 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
28630 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
28640 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e  3_value objects.
28650 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
28660 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76  ct Mem sqlite3_v
28670 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  alue;../*.** CAP
28680 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74  I3REF: SQL Funct
28690 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65  ion Context Obje
286a0 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e  ct.**.** The con
286b0 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e  text in which an
286c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78   SQL function ex
286d0 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64  ecutes is stored
286e0 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   in an.** sqlite
286f0 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
28700 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f  .  ^A pointer to
28710 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74   an sqlite3_cont
28720 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73  ext object.** is
28730 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61   always first pa
28740 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c  rameter to [appl
28750 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
28760 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  SQL functions]..
28770 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
28780 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
28790 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
287a0 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73  tation will pass
287b0 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72   this.** pointer
287c0 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61   through into ca
287d0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
287e0 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c  result_int | sql
287f0 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a  ite3_result()],.
28800 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72  ** [sqlite3_aggr
28810 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d  egate_context()]
28820 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  , [sqlite3_user_
28830 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  data()],.** [sql
28840 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
28850 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69  handle()], [sqli
28860 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
28870 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73  )],.** and/or [s
28880 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
28890 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  ta()]..*/.typede
288a0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
288b0 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33  _context sqlite3
288c0 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a  _context;../*.**
288d0 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69   CAPI3REF: Bindi
288e0 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65  ng Values To Pre
288f0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73  pared Statements
28900 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68  .** KEYWORDS: {h
28910 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  ost parameter} {
28920 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d  host parameters}
28930 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
28940 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52   name}.** KEYWOR
28950 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  DS: {SQL paramet
28960 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  er} {SQL paramet
28970 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20  ers} {parameter 
28980 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e  binding}.**.** ^
28990 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  (In the SQL stat
289a0 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74  ement text input
289b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   to [sqlite3_pre
289c0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69  pare_v2()] and i
289d0 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20  ts variants,.** 
289e0 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20  literals may be 
289f0 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70  replaced by a [p
28a00 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d  arameter] that m
28a10 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f  atches one of fo
28a20 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c  llowing.** templ
28a30 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ates:.**.** <ul>
28a40 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c  .** <li>  ?.** <
28a50 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69  li>  ?NNN.** <li
28a60 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  :VVV.** <li> 
28a70 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24   @VVV.** <li>  $
28a80 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VVV.** </ul>.**.
28a90 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61  ** In the templa
28aa0 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72  tes above, NNN r
28ab0 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74  epresents an int
28ac0 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a  eger literal,.**
28ad0 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65   and VVV represe
28ae0 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65  nts an alphanume
28af0 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29  ric identifier.)
28b00 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f  ^  ^The values o
28b10 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d  f these.** param
28b20 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c  eters (also call
28b30 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74  ed "host paramet
28b40 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51  er names" or "SQ
28b50 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a  L parameters").*
28b60 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69  * can be set usi
28b70 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
28b80 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
28b90 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a   defined here..*
28ba0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
28bb0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
28bc0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
28bd0 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77   routines is alw
28be0 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  ays.** a pointer
28bf0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
28c00 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65  _stmt] object re
28c10 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b  turned from.** [
28c20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
28c30 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  v2()] or its var
28c40 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  iants..**.** ^Th
28c50 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
28c60 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
28c70 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65  f the SQL parame
28c80 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a  ter to be set..*
28c90 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  * ^The leftmost 
28ca0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61  SQL parameter ha
28cb0 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e  s an index of 1.
28cc0 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65    ^When the same
28cd0 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61   named.** SQL pa
28ce0 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20  rameter is used 
28cf0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20  more than once, 
28d00 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
28d10 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65  quent.** occurre
28d20 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61  nces have the sa
28d30 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20  me index as the 
28d40 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65  first occurrence
28d50 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20  ..** ^The index 
28d60 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  for named parame
28d70 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b  ters can be look
28d80 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a  ed up using the.
28d90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
28da0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
28db0 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72  ()] API if desir
28dc0 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a  ed.  ^The index.
28dd0 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61  ** for "?NNN" pa
28de0 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20  rameters is the 
28df0 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a  value of NNN..**
28e00 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20   ^The NNN value 
28e10 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20  must be between 
28e20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74  1 and the [sqlit
28e30 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70  e3_limit()].** p
28e40 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45  arameter [SQLITE
28e50 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
28e60 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74  NUMBER] (default
28e70 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a   value: 999)..**
28e80 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61  .** ^The third a
28e90 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76  rgument is the v
28ea0 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20  alue to bind to 
28eb0 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
28ec0 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20  * ^If the third 
28ed0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
28ee0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
28ef0 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
28f00 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20  _text16().** or 
28f10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
28f20 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  b() is a NULL po
28f30 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 66  inter then the f
28f40 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a  ourth parameter.
28f50 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e  ** is ignored an
28f60 64 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74  d the end result
28f70 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20   is the same as 
28f80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
28f90 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  l()..**.** ^(In 
28fa0 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74  those routines t
28fb0 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74  hat have a fourt
28fc0 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20  h argument, its 
28fd0 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
28fe0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
28ff0 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
29000 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20  .  To be clear: 
29010 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  the value is the
29020 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75  .** number of <u
29030 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68  >bytes</u> in th
29040 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65  e value, not the
29050 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
29060 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20  cters.)^.** ^If 
29070 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
29080 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
29090 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73  bind_text() or s
290a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
290b0 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74  16().** is negat
290c0 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65  ive, then the le
290d0 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69  ngth of the stri
290e0 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  ng is.** the num
290f0 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20  ber of bytes up 
29100 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
29110 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  o terminator..**
29120 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   If the fourth p
29130 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
29140 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20  te3_bind_blob() 
29150 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
29160 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f  n.** the behavio
29170 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
29180 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61  ** If a non-nega
29190 74 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 61  tive fourth para
291a0 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 65  meter is provide
291b0 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  d to sqlite3_bin
291c0 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73  d_text().** or s
291d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
291e0 31 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  16() or sqlite3_
291f0 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74 68  bind_text64() th
29200 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61 6d  en.** that param
29210 65 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65  eter must be the
29220 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20   byte offset.** 
29230 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65  where the NUL te
29240 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f  rminator would o
29250 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68  ccur assuming th
29260 65 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55  e string were NU
29270 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e  L.** terminated.
29280 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61    If any NUL cha
29290 72 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74  racters occur at
292a0 20 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65   byte offsets le
292b0 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20  ss than .** the 
292c0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75  value of the fou
292d0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68  rth parameter th
292e0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  en the resulting
292f0 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69   string value wi
29300 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d  ll.** contain em
29310 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68  bedded NULs.  Th
29320 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72  e result of expr
29330 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e  essions involvin
29340 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74  g strings.** wit
29350 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20  h embedded NULs 
29360 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
29370 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61  .** ^The fifth a
29380 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 42  rgument to the B
29390 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20 62  LOB and string b
293a0 69 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63 65  inding interface
293b0 73 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72 75  s.** is a destru
293c0 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73  ctor used to dis
293d0 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
293e0 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66   or.** string af
293f0 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66  ter SQLite has f
29400 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
29410 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f    ^The destructo
29420 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74  r is called.** t
29430 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
29440 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20   BLOB or string 
29450 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c  even if the call
29460 20 74 6f 20 62 69 6e 64 20 41 50 49 20 66 61 69   to bind API fai
29470 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ls..** ^If the f
29480 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73  ifth argument is
29490 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20  .** the special 
294a0 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54  value [SQLITE_ST
294b0 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69  ATIC], then SQLi
294c0 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
294d0 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  the.** informati
294e0 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c  on is in static,
294f0 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65   unmanaged space
29500 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65   and does not ne
29510 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a  ed to be freed..
29520 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68  ** ^If the fifth
29530 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68   argument has th
29540 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  e value [SQLITE_
29550 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e  TRANSIENT], then
29560 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  .** SQLite makes
29570 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
29580 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74   copy of the dat
29590 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62  a immediately, b
295a0 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c  efore.** the sql
295b0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
295c0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a  utine returns..*
295d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 20  *.** ^The sixth 
295e0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
295f0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28  te3_bind_text64(
29600 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66  ) must be one of
29610 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
29620 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
29630 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
29640 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  BE], or [SQLITE_
29650 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73  UTF16LE].** to s
29660 70 65 63 69 66 79 20 74 68 65 20 65 6e 63 6f 64  pecify the encod
29670 69 6e 67 20 6f 66 20 74 68 65 20 74 65 78 74 20  ing of the text 
29680 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72  in the third par
29690 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74  ameter.  If.** t
296a0 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e  he sixth argumen
296b0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
296c0 64 5f 74 65 78 74 36 34 28 29 20 69 73 20 6e 6f  d_text64() is no
296d0 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  t one of the.** 
296e0 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 73  allowed values s
296f0 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69  hown above, or i
29700 66 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64  f the text encod
29710 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74  ing is different
29720 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e 63  .** from the enc
29730 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 20  oding specified 
29740 62 79 20 74 68 65 20 73 69 78 74 68 20 70 61 72  by the sixth par
29750 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65  ameter, then the
29760 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20   behavior.** is 
29770 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
29780 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
29790 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f  nd_zeroblob() ro
297a0 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c  utine binds a BL
297b0 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74  OB of length N t
297c0 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64  hat.** is filled
297d0 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e   with zeroes.  ^
297e0 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20  A zeroblob uses 
297f0 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f  a fixed amount o
29800 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73  f memory.** (jus
29810 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20  t an integer to 
29820 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77  hold its size) w
29830 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67  hile it is being
29840 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a   processed..** Z
29850 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74  eroblobs are int
29860 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61  ended to serve a
29870 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  s placeholders f
29880 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a  or BLOBs whose.*
29890 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74  * content is lat
298a0 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67  er written using
298b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
298c0 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
298d0 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72  ntal BLOB I/O] r
298e0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e  outines..** ^A n
298f0 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f  egative value fo
29900 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72  r the zeroblob r
29910 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f  esults in a zero
29920 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a  -length BLOB..**
29930 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74  .** ^If any of t
29940 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
29950 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  *() routines are
29960 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
29970 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66  ULL pointer.** f
29980 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  or the [prepared
29990 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77   statement] or w
299a0 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73  ith a prepared s
299b0 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69  tatement for whi
299c0 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  ch.** [sqlite3_s
299d0 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20  tep()] has been 
299e0 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65  called more rece
299f0 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74  ntly than [sqlit
29a00 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20  e3_reset()],.** 
29a10 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69  then the call wi
29a20 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
29a30 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61  E_MISUSE].  If a
29a40 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ny sqlite3_bind_
29a50 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73  ().** routine is
29a60 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61   passed a [prepa
29a70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
29a80 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e  hat has been fin
29a90 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72  alized, the.** r
29aa0 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
29ab0 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
29ac0 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  harmful..**.** ^
29ad0 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74  Bindings are not
29ae0 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20   cleared by the 
29af0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
29b00 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55  ] routine..** ^U
29b10 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  nbound parameter
29b20 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
29b30 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  d as NULL..**.**
29b40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
29b50 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65  nd_* routines re
29b60 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
29b70 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61   on success or a
29b80 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  n.** [error code
29b90 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f  ] if anything go
29ba0 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53  es wrong..** ^[S
29bb0 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69  QLITE_TOOBIG] mi
29bc0 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20  ght be returned 
29bd0 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  if the size of a
29be0 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a   string or BLOB.
29bf0 2a 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69 74  ** exceeds limit
29c00 73 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73 71  s imposed by [sq
29c10 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
29c20 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
29c30 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  H]) or.** [SQLIT
29c40 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a  E_MAX_LENGTH]..*
29c50 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  * ^[SQLITE_RANGE
29c60 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
29c70 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   the parameter.*
29c80 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  * index is out o
29c90 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49  f range.  ^[SQLI
29ca0 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74  TE_NOMEM] is ret
29cb0 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28  urned if malloc(
29cc0 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53  ) fails..**.** S
29cd0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
29ce0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
29cf0 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73  _count()],.** [s
29d00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
29d10 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
29d20 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
29d30 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
29d40 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
29d50 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71  te3_bind_blob(sq
29d60 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
29d70 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
29d80 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
29d90 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
29da0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73  e3_bind_blob64(s
29db0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
29dc0 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
29dd0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a  sqlite3_uint64,.
29de0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29df0 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28          void(*)(
29e00 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
29e10 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65  ite3_bind_double
29e20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29e30 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e  int, double);.in
29e40 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
29e50 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
29e60 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74  , int, int);.int
29e70 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
29e80 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
29e90 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
29ea0 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69  int64);.int sqli
29eb0 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71  te3_bind_null(sq
29ec0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
29ed0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
29ee0 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ind_text(sqlite3
29ef0 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74  _stmt*,int,const
29f00 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28   char*,int,void(
29f10 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
29f20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
29f30 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
29f40 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
29f50 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
29f60 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
29f70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
29f80 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
29f90 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61  , int, const cha
29fa0 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  r*, sqlite3_uint
29fb0 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  64,.            
29fc0 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
29fd0 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73  d(*)(void*), uns
29fe0 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64  igned char encod
29ff0 69 6e 67 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ing);.int sqlite
2a000 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c  3_bind_value(sql
2a010 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2a020 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76   const sqlite3_v
2a030 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
2a040 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
2a050 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
2a060 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f   int, int n);../
2a070 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2a080 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72  umber Of SQL Par
2a090 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54  ameters.**.** ^T
2a0a0 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  his routine can 
2a0b0 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20  be used to find 
2a0c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53  the number of [S
2a0d0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a  QL parameters].*
2a0e0 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64  * in a [prepared
2a0f0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51   statement].  SQ
2a100 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  L parameters are
2a110 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a   tokens of the.*
2a120 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e  * form "?", "?NN
2a130 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41  N", ":AAA", "$AA
2a140 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68  A", or "@AAA" th
2a150 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70  at serve as.** p
2a160 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
2a170 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20  values that are 
2a180 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2a190 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74  ob | bound].** t
2a1a0 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73  o the parameters
2a1b0 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65   at a later time
2a1c0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72  ..**.** ^(This r
2a1d0 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20  outine actually 
2a1e0 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65  returns the inde
2a1f0 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  x of the largest
2a200 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20   (rightmost).** 
2a210 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61  parameter. For a
2a220 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20  ll forms except 
2a230 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20  ?NNN, this will 
2a240 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68  correspond to th
2a250 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75  e.** number of u
2a260 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73  nique parameters
2a270 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73  .  If parameters
2a280 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72   of the ?NNN for
2a290 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74  m are used,.** t
2a2a0 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73  here may be gaps
2a2b0 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a   in the list.)^.
2a2c0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2a2d0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2a2e0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
2a2f0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2a300 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2a310 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ame()], and.** [
2a320 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2a330 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
2a340 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2a350 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
2a360 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
2a370 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2a380 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20  3REF: Name Of A 
2a390 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a  Host Parameter.*
2a3a0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2a3b0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2a3c0 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72  _name(P,N) inter
2a3d0 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
2a3e0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2a3f0 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65  N-th [SQL parame
2a400 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65  ter] in the [pre
2a410 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a420 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72   P..** ^(SQL par
2a430 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
2a440 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  orm "?NNN" or ":
2a450 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
2a460 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65  r "$AAA".** have
2a470 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73   a name which is
2a480 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e   the string "?NN
2a490 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
2a4a0 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
2a4b0 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
2a4c0 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  ..** In other wo
2a4d0 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c  rds, the initial
2a4e0 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22   ":" or "$" or "
2a4f0 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20  @" or "?".** is 
2a500 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74  included as part
2a510 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a   of the name.)^.
2a520 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f  ** ^Parameters o
2a530 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77  f the form "?" w
2a540 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69  ithout a followi
2a550 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20  ng integer have 
2a560 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61  no name.** and a
2a570 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61  re referred to a
2a580 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20  s "nameless" or 
2a590 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d  "anonymous param
2a5a0 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eters"..**.** ^T
2a5b0 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61  he first host pa
2a5c0 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
2a5d0 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30  ndex of 1, not 0
2a5e0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2a5f0 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f  value N is out o
2a600 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68  f range or if th
2a610 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72  e N-th parameter
2a620 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c   is.** nameless,
2a630 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65   then NULL is re
2a640 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65  turned.  ^The re
2a650 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
2a660 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54  .** always in UT
2a670 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65  F-8 encoding eve
2a680 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70  n if the named p
2a690 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20  arameter was.** 
2a6a0 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69  originally speci
2a6b0 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69  fied as UTF-16 i
2a6c0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
2a6d0 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  re16()] or.** [s
2a6e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2a6f0 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
2a700 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2a710 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
2a720 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
2a730 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2a740 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
2a750 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2a760 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2a770 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e  index()]..*/.con
2a780 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2a790 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2a7a0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
2a7b0 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  t*, int);../*.**
2a7c0 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78   CAPI3REF: Index
2a7d0 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20   Of A Parameter 
2a7e0 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d  With A Given Nam
2a7f0 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  e.**.** ^Return 
2a800 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  the index of an 
2a810 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69  SQL parameter gi
2a820 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e  ven its name.  ^
2a830 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c  The.** index val
2a840 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73  ue returned is s
2a850 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20  uitable for use 
2a860 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
2a870 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
2a880 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2a890 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2a8a0 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73  .  ^A zero.** is
2a8b0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20   returned if no 
2a8c0 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74  matching paramet
2a8d0 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54  er is found.  ^T
2a8e0 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
2a8f0 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76  name must be giv
2a900 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e  en in UTF-8 even
2a910 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   if the original
2a920 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61   statement.** wa
2a930 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20  s prepared from 
2a940 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e  UTF-16 text usin
2a950 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
2a960 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
2a970 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2a980 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
2a990 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
2a9a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2a9b0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
2a9c0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2a9d0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2a9e0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
2a9f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2aa00 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2aa10 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  x(sqlite3_stmt*,
2aa20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
2aa30 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
2aa40 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20  3REF: Reset All 
2aa50 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72  Bindings On A Pr
2aa60 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2aa70 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79  .**.** ^Contrary
2aa80 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f   to the intuitio
2aa90 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69  n of many, [sqli
2aaa0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65  te3_reset()] doe
2aab0 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74  s not reset.** t
2aac0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
2aad0 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73  _blob | bindings
2aae0 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  ] on a [prepared
2aaf0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
2ab00 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e  ^Use this routin
2ab10 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68  e to reset all h
2ab20 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ost parameters t
2ab30 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73  o NULL..*/.int s
2ab40 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
2ab50 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
2ab60 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2ab70 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
2ab80 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65   Columns In A Re
2ab90 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult Set.**.** ^
2aba0 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65  Return the numbe
2abb0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2abc0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72  the result set r
2abd0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
2abe0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2abf0 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f  ement]. ^This ro
2ac00 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
2ac10 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53  if pStmt is an S
2ac20 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
2ac30 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65  that does not re
2ac40 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65  turn data (for e
2ac50 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54  xample an [UPDAT
2ac60 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  E])..**.** See a
2ac70 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61  lso: [sqlite3_da
2ac80 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69  ta_count()].*/.i
2ac90 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2aca0 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
2acb0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2acc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
2acd0 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
2ace0 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a   Result Set.**.*
2acf0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
2ad00 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
2ad10 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
2ad20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
2ad30 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
2ad40 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
2ad50 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
2ad60 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
2ad70 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
2ad80 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2ad90 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2ada0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
2adb0 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
2adc0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2add0 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75  mn_name16() retu
2ade0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2adf0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
2ae00 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
2ae10 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ing.  ^The first
2ae20 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2ae30 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2ae40 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69  ement].** that i
2ae50 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53  mplements the [S
2ae60 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2ae70 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
2ae80 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
2ae90 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  * column number.
2aea0 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20    ^The leftmost 
2aeb0 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72  column is number
2aec0 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72   0..**.** ^The r
2aed0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
2aee0 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
2aef0 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
2af00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2af10 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74  ment].** is dest
2af20 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
2af30 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
2af40 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
2af50 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
2af60 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
2af70 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
2af80 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2af90 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
2afa0 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
2afb0 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e  * or until the n
2afc0 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  ext call to.** s
2afd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2afe0 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
2aff0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
2b000 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
2b010 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71  mn..**.** ^If sq
2b020 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66  lite3_malloc() f
2b030 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20  ails during the 
2b040 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69  processing of ei
2b050 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  ther routine.** 
2b060 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72  (for example dur
2b070 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  ing a conversion
2b080 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55   from UTF-8 to U
2b090 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a  TF-16) then a.**
2b0a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
2b0b0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2b0c0 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20   ^The name of a 
2b0d0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
2b0e0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
2b0f0 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f  e "AS" clause fo
2b100 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e  r.** that column
2b110 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e  , if there is an
2b120 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20   AS clause.  If 
2b130 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63  there is no AS c
2b140 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68  lause.** then th
2b150 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
2b160 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66  lumn is unspecif
2b170 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e  ied and may chan
2b180 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72  ge from.** one r
2b190 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
2b1a0 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f   to the next..*/
2b1b0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
2b1c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2b1d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2b1e0 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f  int N);.const vo
2b1f0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2b200 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  mn_name16(sqlite
2b210 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
2b220 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b230 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61  : Source Of Data
2b240 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75   In A Query Resu
2b250 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  lt.**.** ^These 
2b260 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65  routines provide
2b270 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65   a means to dete
2b280 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61  rmine the databa
2b290 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a  se, table, and.*
2b2a0 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  * table column t
2b2b0 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69  hat is the origi
2b2c0 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61  n of a particula
2b2d0 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  r result column 
2b2e0 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73  in.** [SELECT] s
2b2f0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  tatement..** ^Th
2b300 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
2b310 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20  tabase or table 
2b320 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65  or column can be
2b330 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20   returned as.** 
2b340 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f  either a UTF-8 o
2b350 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  r UTF-16 string.
2b360 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65    ^The _database
2b370 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
2b380 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
2b390 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62  e name, the _tab
2b3a0 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  le_ routines ret
2b3b0 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61  urn the table na
2b3c0 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f  me, and.** the o
2b3d0 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20  rigin_ routines 
2b3e0 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d  return the colum
2b3f0 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20  n name..** ^The 
2b400 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
2b410 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74  is valid until t
2b420 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2b430 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72  tement] is destr
2b440 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  oyed.** using [s
2b450 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2b460 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
2b470 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74  statement is aut
2b480 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65  omatically.** re
2b490 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20  prepared by the 
2b4a0 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73  first call to [s
2b4b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
2b4c0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
2b4d0 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  run.** or until 
2b4e0 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
2b4f0 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65  tion is requeste
2b500 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20  d.** again in a 
2b510 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69  different encodi
2b520 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  ng..**.** ^The n
2b530 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72  ames returned ar
2b540 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75  e the original u
2b550 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20  n-aliased names 
2b560 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  of the.** databa
2b570 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63  se, table, and c
2b580 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  olumn..**.** ^Th
2b590 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2b5a0 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
2b5b0 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61  aces is a [prepa
2b5c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
2b5d0 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
2b5e0 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  ons return infor
2b5f0 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
2b600 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
2b610 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  mn returned by.*
2b620 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c  * the statement,
2b630 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
2b640 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
2b650 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
2b660 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75  e left-most colu
2b670 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66  mn is column 0 f
2b680 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  or these routine
2b690 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  s..**.** ^If the
2b6a0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75   Nth column retu
2b6b0 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74  rned by the stat
2b6c0 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72  ement is an expr
2b6d0 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62  ession or.** sub
2b6e0 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74  query and is not
2b6f0 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c   a column value,
2b700 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65   then all of the
2b710 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
2b720 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54  urn.** NULL.  ^T
2b730 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67  hese routine mig
2b740 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e  ht also return N
2b750 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20  ULL if a memory 
2b760 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
2b770 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74  .** occurs.  ^Ot
2b780 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65  herwise, they re
2b790 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  turn the name of
2b7a0 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61   the attached da
2b7b0 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a  tabase, table,.*
2b7c0 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74  * or column that
2b7d0 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f   query result co
2b7e0 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74  lumn was extract
2b7f0 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  ed from..**.** ^
2b800 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65  As with all othe
2b810 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74  r SQLite APIs, t
2b820 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73  hose whose names
2b830 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72   end with "16" r
2b840 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20  eturn.** UTF-16 
2b850 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20  encoded strings 
2b860 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75  and the other fu
2b870 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55  nctions return U
2b880 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  TF-8..**.** ^The
2b890 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79  se APIs are only
2b8a0 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68   available if th
2b8b0 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f  e library was co
2b8c0 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
2b8d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
2b8e0 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54  E_COLUMN_METADAT
2b8f0 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f  A] C-preprocesso
2b900 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20  r symbol..**.** 
2b910 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
2b920 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
2b930 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65  or more of these
2b940 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73   routines agains
2b950 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72  t the same.** pr
2b960 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b970 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74   and column at t
2b980 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
2b990 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
2b9a0 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  e.** undefined..
2b9b0 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
2b9c0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
2b9d0 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  l one or more.**
2b9e0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2b9f0 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c  _database_name |
2ba00 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61   column metadata
2ba10 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20   interfaces].** 
2ba20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72  for the same [pr
2ba30 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ba40 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c  ] and result col
2ba50 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61  umn.** at the sa
2ba60 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
2ba70 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
2ba80 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74  efined..*/.const
2ba90 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2baa0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
2bab0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2bac0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
2bad0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2bae0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
2baf0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2bb00 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
2bb10 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2bb20 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c  n_table_name(sql
2bb30 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2bb40 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2bb50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
2bb60 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
2bb70 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
2bb80 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2bb90 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
2bba0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2bbb0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
2bbc0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2bbd0 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36  mn_origin_name16
2bbe0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2bbf0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2bc00 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44  3REF: Declared D
2bc10 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65  atatype Of A Que
2bc20 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20  ry Result.**.** 
2bc30 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61  ^(The first para
2bc40 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70  meter is a [prep
2bc50 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2bc60 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74  .** If this stat
2bc70 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45  ement is a [SELE
2bc80 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  CT] statement an
2bc90 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  d the Nth column
2bca0 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72   of the.** retur
2bcb0 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f  ned result set o
2bcc0 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20  f that [SELECT] 
2bcd0 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  is a table colum
2bce0 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70  n (not an.** exp
2bcf0 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
2bd00 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65  ery) then the de
2bd10 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74  clared type of t
2bd20 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75  he table.** colu
2bd30 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  mn is returned.)
2bd40 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ^  ^If the Nth c
2bd50 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
2bd60 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a  ult set is an.**
2bd70 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
2bd80 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20  ubquery, then a 
2bd90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
2bda0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68  returned..** ^Th
2bdb0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
2bdc0 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d  g is always UTF-
2bdd0 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a  8 encoded..**.**
2bde0 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
2bdf0 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61  given the databa
2be00 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a  se schema:.**.**
2be10 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31   CREATE TABLE t1
2be20 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a  (c1 VARIANT);.**
2be30 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c  .** and the foll
2be40 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  owing statement 
2be50 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a  to be compiled:.
2be60 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20  **.** SELECT c1 
2be70 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b  + 1, c1 FROM t1;
2be80 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  .**.** this rout
2be90 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  ine would return
2bea0 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52   the string "VAR
2beb0 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65  IANT" for the se
2bec0 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  cond result.** c
2bed0 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e  olumn (i==1), an
2bee0 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
2bef0 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72   for the first r
2bf00 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
2bf10 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51  =0).)^.**.** ^SQ
2bf20 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
2bf30 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e  c run-time typin
2bf40 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63  g.  ^So just bec
2bf50 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  ause a column.**
2bf60 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20   is declared to 
2bf70 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63  contain a partic
2bf80 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e  ular type does n
2bf90 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ot mean that the
2bfa0 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20  .** data stored 
2bfb0 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69  in that column i
2bfc0 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65  s of the declare
2bfd0 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20  d type.  SQLite 
2bfe0 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74  is.** strongly t
2bff0 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79  yped, but the ty
2c000 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20  ping is dynamic 
2c010 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79  not static.  ^Ty
2c020 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61  pe.** is associa
2c030 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64  ted with individ
2c040 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20  ual values, not 
2c050 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e  with the contain
2c060 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68  ers.** used to h
2c070 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73  old those values
2c080 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
2c090 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2c0a0 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33  decltype(sqlite3
2c0b0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
2c0c0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2c0d0 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
2c0e0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2c0f0 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
2c100 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65  PI3REF: Evaluate
2c110 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
2c120 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20  t.**.** After a 
2c130 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2c140 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72  ent] has been pr
2c150 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74  epared using eit
2c160 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
2c170 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2c180 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2c190 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  e16_v2()] or one
2c1a0 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a   of the legacy.*
2c1b0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  * interfaces [sq
2c1c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
2c1d0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2c1e0 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20  pare16()], this 
2c1f0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  function.** must
2c200 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   be called one o
2c210 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
2c220 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61  evaluate the sta
2c230 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  tement..**.** Th
2c240 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65  e details of the
2c250 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65   behavior of the
2c260 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2c270 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64  interface depend
2c280 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74  .** on whether t
2c290 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
2c2a0 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
2c2b0 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69  the newer "v2" i
2c2c0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c  nterface.** [sql
2c2d0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2c2e0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2c2f0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
2c300 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67  or the older leg
2c310 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
2c320 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2c330 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
2c340 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20  3_prepare16()]. 
2c350 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a   The use of the.
2c360 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65  ** new "v2" inte
2c370 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
2c380 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70  nded for new app
2c390 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68  lications but th
2c3a0 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
2c3b0 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69  rface will conti
2c3c0 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72  nue to be suppor
2c3d0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74  ted..**.** ^In t
2c3e0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
2c3f0 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ace, the return 
2c400 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69  value will be ei
2c410 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53  ther [SQLITE_BUS
2c420 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  Y],.** [SQLITE_D
2c430 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f  ONE], [SQLITE_RO
2c440 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  W], [SQLITE_ERRO
2c450 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  R], or [SQLITE_M
2c460 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68  ISUSE]..** ^With
2c470 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
2c480 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20  ace, any of the 
2c490 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f  other [result co
2c4a0 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  des] or.** [exte
2c4b0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
2c4c0 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  s] might be retu
2c4d0 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a  rned as well..**
2c4e0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53  .** ^[SQLITE_BUS
2c4f0 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  Y] means that th
2c500 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
2c510 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20  e was unable to 
2c520 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64  acquire the.** d
2c530 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74  atabase locks it
2c540 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73   needs to do its
2c550 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73   job.  ^If the s
2c560 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43  tatement is a [C
2c570 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63  OMMIT].** or occ
2c580 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61  urs outside of a
2c590 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
2c5a0 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75  action, then you
2c5b0 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a   can retry the.*
2c5c0 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  * statement.  If
2c5d0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2c5e0 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d  s not a [COMMIT]
2c5f0 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68   and occurs with
2c600 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69  in an.** explici
2c610 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68  t transaction th
2c620 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f  en you should ro
2c630 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  llback the trans
2c640 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a  action before.**
2c650 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a   continuing..**.
2c660 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ** ^[SQLITE_DONE
2c670 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
2c680 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66   statement has f
2c690 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
2c6a0 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  g.** successfull
2c6b0 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  y.  sqlite3_step
2c6c0 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
2c6d0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
2c6e0 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a   this virtual.**
2c6f0 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74   machine without
2c700 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b   first calling [
2c710 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2c720 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69   to reset the vi
2c730 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
2c740 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
2c750 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  tial state..**.*
2c760 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74  * ^If the SQL st
2c770 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78  atement being ex
2c780 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61  ecuted returns a
2c790 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53  ny data, then [S
2c7a0 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73  QLITE_ROW].** is
2c7b0 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74   returned each t
2c7c0 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66  ime a new row of
2c7d0 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66   data is ready f
2c7e0 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79  or processing by
2c7f0 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20   the.** caller. 
2c800 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62  The values may b
2c810 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67  e accessed using
2c820 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63   the [column acc
2c830 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  ess functions]..
2c840 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
2c850 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69  ) is called agai
2c860 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68  n to retrieve th
2c870 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61  e next row of da
2c880 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ta..**.** ^[SQLI
2c890 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20  TE_ERROR] means 
2c8a0 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20  that a run-time 
2c8b0 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61  error (such as a
2c8c0 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76   constraint.** v
2c8d0 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63  iolation) has oc
2c8e0 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33  curred.  sqlite3
2c8f0 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
2c900 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
2c910 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e  in on.** the VM.
2c920 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f   More informatio
2c930 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62  n may be found b
2c940 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
2c950 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a  e3_errmsg()]..**
2c960 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63   ^With the legac
2c970 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d  y interface, a m
2c980 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
2c990 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61  or code (for exa
2c9a0 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  mple,.** [SQLITE
2c9b0 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51  _INTERRUPT], [SQ
2c9c0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53  LITE_SCHEMA], [S
2c9d0 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20  QLITE_CORRUPT], 
2c9e0 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a  and so forth).**
2c9f0 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
2ca00 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
2ca10 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e  ite3_reset()] on
2ca20 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2ca30 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e  d statement].  ^
2ca40 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
2ca50 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f  rface,.** the mo
2ca60 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
2ca70 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
2ca80 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73  ed directly by s
2ca90 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a  qlite3_step()..*
2caa0 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53  *.** [SQLITE_MIS
2cab0 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USE] means that 
2cac0 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  the this routine
2cad0 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70   was called inap
2cae0 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20  propriately..** 
2caf0 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63  Perhaps it was c
2cb00 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70  alled on a [prep
2cb10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2cb20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65  that has.** alre
2cb30 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65  ady been [sqlite
2cb40 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2cb50 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e  alized] or on on
2cb60 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72  e that had.** pr
2cb70 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
2cb80 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
2cb90 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
2cba0 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a  ].  Or it could.
2cbb0 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74  ** be the case t
2cbc0 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74  hat the same dat
2cbd0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2cbe0 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62   is being used b
2cbf0 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65  y two or.** more
2cc00 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
2cc10 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74  same moment in t
2cc20 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61  ime..**.** For a
2cc30 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ll versions of S
2cc40 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20  QLite up to and 
2cc50 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33  including 3.6.23
2cc60 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a  .1, a call to.**
2cc70 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2cc80 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20  )] was required 
2cc90 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74  after sqlite3_st
2cca0 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e  ep() returned an
2ccb0 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20  ything.** other 
2ccc0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
2ccd0 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62  ] before any sub
2cce0 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
2ccf0 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33  on of.** sqlite3
2cd00 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72  _step().  Failur
2cd10 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70  e to reset the p
2cd20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2cd30 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  t using .** [sql
2cd40 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f  ite3_reset()] wo
2cd50 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e  uld result in an
2cd60 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2cd70 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20   return from.** 
2cd80 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
2cd90 20 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69   But after versi
2cda0 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c  on 3.6.23.1, sql
2cdb0 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61  ite3_step() bega
2cdc0 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71  n.** calling [sq
2cdd0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61  lite3_reset()] a
2cde0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20  utomatically in 
2cdf0 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63  this circumstanc
2ce00 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e  e rather.** than
2ce10 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
2ce20 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69  TE_MISUSE].  Thi
2ce30 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65  s is not conside
2ce40 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c  red a compatibil
2ce50 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63  ity.** break bec
2ce60 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61  ause any applica
2ce70 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72  tion that ever r
2ce80 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54  eceives an SQLIT
2ce90 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a  E_MISUSE error.*
2cea0 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64  * is broken by d
2ceb0 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20  efinition.  The 
2cec0 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
2ced0 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d  ORESET] compile-
2cee0 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63  time option.** c
2cef0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
2cf00 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79  store the legacy
2cf10 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
2cf20 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66   <b>Goofy Interf
2cf30 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49  ace Alert:</b> I
2cf40 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
2cf50 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69  erface, the sqli
2cf60 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50  te3_step().** AP
2cf70 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  I always returns
2cf80 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72   a generic error
2cf90 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45   code, [SQLITE_E
2cfa0 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67  RROR], following
2cfb0 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74   any.** error ot
2cfc0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
2cfd0 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49  _BUSY] and [SQLI
2cfe0 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75  TE_MISUSE].  You
2cff0 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73   must call.** [s
2d000 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2d010 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
2d020 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72  lize()] in order
2d030 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20   to find one of 
2d040 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
2d050 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68  [error codes] th
2d060 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69  at better descri
2d070 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a  bes the error..*
2d080 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20  * We admit that 
2d090 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20  this is a goofy 
2d0a0 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f  design.  The pro
2d0b0 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69  blem has been fi
2d0c0 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  xed.** with the 
2d0d0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20  "v2" interface. 
2d0e0 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20   If you prepare 
2d0f0 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20  all of your SQL 
2d100 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73  statements.** us
2d110 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
2d120 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2d130 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
2d140 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e  epare16_v2()] in
2d150 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20  stead.** of the 
2d160 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f  legacy [sqlite3_
2d170 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
2d180 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2d190 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c  6()] interfaces,
2d1a0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72  .** then the mor
2d1b0 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  e specific [erro
2d1c0 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74  r codes] are ret
2d1d0 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a  urned directly.*
2d1e0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  * by sqlite3_ste
2d1f0 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66  p().  The use of
2d200 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
2d210 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
2d220 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
2d230 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f  e3_step(sqlite3_
2d240 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
2d250 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
2d260 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
2d270 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a  result set.**.**
2d280 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
2d290 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65  ta_count(P) inte
2d2a0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
2d2b0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
2d2c0 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75  mns in the.** cu
2d2d0 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
2d2e0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b   result set of [
2d2f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d300 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72  nt] P..** ^If pr
2d310 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d320 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65   P does not have
2d330 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74   results ready t
2d340 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61  o return.** (via
2d350 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73   calls to the [s
2d360 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
2d370 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t | sqlite3_colu
2d380 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e  mn_*()] of.** in
2d390 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73  terfaces) then s
2d3a0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2d3b0 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a  t(P) returns 0..
2d3c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2d3d0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
2d3e0 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72  utine also retur
2d3f0 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e  ns 0 if P is a N
2d400 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20  ULL pointer..** 
2d410 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2d420 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69  a_count(P) routi
2d430 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
2d440 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
2d450 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
2d460 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e  _step](P) return
2d470 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ed [SQLITE_DONE]
2d480 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
2d490 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a  data_count(P).**
2d4a0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e   will return non
2d4b0 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75  -zero if previou
2d4c0 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  s call to [sqlit
2d4d0 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75  e3_step](P) retu
2d4e0 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rned.** [SQLITE_
2d4f0 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20  ROW], except in 
2d500 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20  the case of the 
2d510 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e  [PRAGMA incremen
2d520 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77  tal_vacuum].** w
2d530 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72  here it always r
2d540 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63  eturns zero sinc
2d550 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74  e each step of t
2d560 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a  hat multi-step.*
2d570 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73  * pragma returns
2d580 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61   0 columns of da
2d590 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ta..**.** See al
2d5a0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  so: [sqlite3_col
2d5b0 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  umn_count()].*/.
2d5c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61  int sqlite3_data
2d5d0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
2d5e0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2d5f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
2d600 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79  ndamental Dataty
2d610 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
2d620 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a   SQLITE_TEXT.**.
2d630 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65  ** ^(Every value
2d640 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f   in SQLite has o
2d650 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61  ne of five funda
2d660 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73  mental datatypes
2d670 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
2d680 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e  <li> 64-bit sign
2d690 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c  ed integer.** <l
2d6a0 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66  i> 64-bit IEEE f
2d6b0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
2d6c0 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72  mber.** <li> str
2d6d0 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42  ing.** <li> BLOB
2d6e0 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a  .** <li> NULL.**
2d6f0 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
2d700 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
2d710 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63  re codes for eac
2d720 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73  h of those types
2d730 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
2d740 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58  t the SQLITE_TEX
2d750 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61  T constant was a
2d760 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69  lso used in SQLi
2d770 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20  te version 2.** 
2d780 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79  for a completely
2d790 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69   different meani
2d7a0 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  ng.  Software th
2d7b0 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74  at links against
2d7c0 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20   both.** SQLite 
2d7d0 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51  version 2 and SQ
2d7e0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73  Lite version 3 s
2d7f0 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45  hould use SQLITE
2d800 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53  3_TEXT, not.** S
2d810 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23  QLITE_TEXT..*/.#
2d820 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
2d830 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65  TEGER  1.#define
2d840 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20   SQLITE_FLOAT   
2d850 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
2d860 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65  E_BLOB     4.#de
2d870 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c  fine SQLITE_NULL
2d880 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51       5.#ifdef SQ
2d890 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65  LITE_TEXT.# unde
2d8a0 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65  f SQLITE_TEXT.#e
2d8b0 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  lse.# define SQL
2d8c0 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23  ITE_TEXT     3.#
2d8d0 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51  endif.#define SQ
2d8e0 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33  LITE3_TEXT     3
2d8f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2d900 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20  : Result Values 
2d910 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20  From A Query.** 
2d920 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d  KEYWORDS: {colum
2d930 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
2d940 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ns}.**.** These 
2d950 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68  routines form th
2d960 65 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69  e "result set" i
2d970 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
2d980 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
2d990 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
2d9a0 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c  on about a singl
2d9b0 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  e column of the 
2d9c0 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c  current.** resul
2d9d0 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79  t row of a query
2d9e0 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73  .  ^In every cas
2d9f0 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  e the first argu
2da00 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
2da10 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65  r.** to the [pre
2da20 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2da30 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65   that is being e
2da40 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73  valuated (the [s
2da50 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a  qlite3_stmt*].**
2da60 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
2da70 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
2da80 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2da90 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72  r one of its var
2daa0 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68  iants).** and th
2dab0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
2dac0 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
2dad0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72  f the column for
2dae0 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69   which informati
2daf0 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
2db00 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c  returned. ^The l
2db10 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f  eftmost column o
2db20 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2db30 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30   has the index 0
2db40 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72  ..** ^The number
2db50 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
2db60 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65  he result can be
2db70 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e   determined usin
2db80 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  g.** [sqlite3_co
2db90 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a  lumn_count()]..*
2dba0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20  *.** If the SQL 
2dbb0 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
2dbc0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69  ot currently poi
2dbd0 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f  nt to a valid ro
2dbe0 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20  w, or if the.** 
2dbf0 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20  column index is 
2dc00 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68  out of range, th
2dc10 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  e result is unde
2dc20 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20  fined..** These 
2dc30 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c  routines may onl
2dc40 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e  y be called when
2dc50 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2dc60 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
2dc70 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
2dc80 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
2dc90 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68  E_ROW] and neith
2dca0 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  er.** [sqlite3_r
2dcb0 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c  eset()] nor [sql
2dcc0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2dcd0 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
2dce0 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a  d subsequently..
2dcf0 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65  ** If any of the
2dd00 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
2dd10 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
2dd20 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2dd30 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
2dd40 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  nalize()] or aft
2dd50 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  er [sqlite3_step
2dd60 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
2dd70 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74  .** something ot
2dd80 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
2dd90 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c  _ROW], the resul
2dda0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
2ddb0 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33  ..** If [sqlite3
2ddc0 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
2ddd0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2dde0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2ddf0 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c  ze()].** are cal
2de00 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65  led from a diffe
2de10 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c  rent thread whil
2de20 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  e any of these r
2de30 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70  outines.** are p
2de40 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  ending, then the
2de50 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
2de60 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
2de70 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2de80 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65  n_type() routine
2de90 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
2dea0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
2deb0 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d  | datatype code]
2dec0 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c   for the initial
2ded0 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66   data type.** of
2dee0 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75   the result colu
2def0 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  mn.  ^The return
2df00 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20  ed value is one 
2df10 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  of [SQLITE_INTEG
2df20 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ER],.** [SQLITE_
2df30 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  FLOAT], [SQLITE_
2df40 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  TEXT], [SQLITE_B
2df50 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  LOB], or [SQLITE
2df60 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c  _NULL].  The val
2df70 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  ue.** returned b
2df80 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2df90 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20  _type() is only 
2dfa0 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f  meaningful if no
2dfb0 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73   type.** convers
2dfc0 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72  ions have occurr
2dfd0 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20  ed as described 
2dfe0 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20  below.  After a 
2dff0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c  type conversion,
2e000 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65  .** the value re
2e010 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2e020 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
2e030 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46  is undefined.  F
2e040 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  uture.** version
2e050 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  s of SQLite may 
2e060 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76  change the behav
2e070 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  ior of sqlite3_c
2e080 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20  olumn_type().** 
2e090 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65  following a type
2e0a0 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
2e0b0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2e0c0 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
2e0d0 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e  TF-8 string then
2e0e0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
2e0f0 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72  umn_bytes().** r
2e100 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
2e110 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2e120 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
2e130 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
2e140 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2e150 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c  a UTF-16 string,
2e160 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2e170 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e  lumn_bytes() con
2e180 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
2e190 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64  ing to UTF-8 and
2e1a0 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
2e1b0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2e1c0 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
2e1d0 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
2e1e0 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
2e1f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2e200 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  s() uses.** [sql
2e210 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
2e220 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
2e230 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
2e240 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  8 string and ret
2e250 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
2e260 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2e270 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
2e280 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2e290 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69   NULL, then sqli
2e2a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2e2b0 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  () returns zero.
2e2c0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
2e2d0 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
2e2e0 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
2e2f0 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
2e300 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2e310 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
2e320 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2e330 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
2e340 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
2e350 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2e360 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73  ult is a UTF-8 s
2e370 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
2e380 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2e390 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  16() converts.**
2e3a0 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
2e3b0 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72  TF-16 and then r
2e3c0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2e3d0 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
2e3e0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2e3f0 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
2e400 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2e410 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75  lumn_bytes16() u
2e420 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
2e430 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
2e440 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
2e450 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74  e to a UTF-16 st
2e460 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
2e470 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
2e480 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
2e490 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
2e4a0 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c  he result is NUL
2e4b0 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  L, then sqlite3_
2e4c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2e4d0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
2e4e0 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73  *.** ^The values
2e4f0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
2e500 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2e510 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73  es()] and .** [s
2e520 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2e530 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20  tes16()] do not 
2e540 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f  include the zero
2e550 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20   terminators at 
2e560 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68  the end.** of th
2e570 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20  e string.  ^For 
2e580 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c  clarity: the val
2e590 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ues returned by.
2e5a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2e5b0 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20  mn_bytes()] and 
2e5c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2e5d0 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74  bytes16()] are t
2e5e0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
2e5f0 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
2e600 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  ing, not the num
2e610 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
2e620 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67  s..**.** ^String
2e630 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  s returned by sq
2e640 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2e650 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
2e660 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c  column_text16(),
2e670 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73  .** even empty s
2e680 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61  trings, are alwa
2e690 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
2e6a0 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
2e6b0 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  .** value from s
2e6c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2e6d0 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d  ob() for a zero-
2e6e0 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61  length BLOB is a
2e6f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
2e700 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74  *.** ^The object
2e710 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
2e720 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
2e730 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b  ue()] is an.** [
2e740 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2e750 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2e760 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74  t.  An unprotect
2e770 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2e780 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f   object.** may o
2e790 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
2e7a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
2e7b0 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
2e7c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
2e7d0 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  e()]..** If the 
2e7e0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
2e7f0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2e800 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
2e810 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2e820 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73  n_value()] is us
2e830 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20  ed in any other 
2e840 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63  way, including c
2e850 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69  alls.** to routi
2e860 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
2e870 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20  3_value_int()], 
2e880 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2e890 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
2e8a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
2e8b0 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  es()], then the 
2e8c0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
2e8d0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
2e8e0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65  se routines atte
2e8f0 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  mpt to convert t
2e900 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61  he value where a
2e910 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f  ppropriate.  ^Fo
2e920 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66  r.** example, if
2e930 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
2e940 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20  presentation is 
2e950 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74  FLOAT and a text
2e960 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65   result.** is re
2e970 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65  quested, [sqlite
2e980 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73  3_snprintf()] is
2e990 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
2e9a0 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a   to perform the.
2e9b0 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75  ** conversion au
2e9c0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28  tomatically.  ^(
2e9d0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61  The following ta
2e9e0 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20  ble details the 
2e9f0 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74  conversions.** t
2ea00 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a  hat are applied:
2ea10 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
2ea20 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  te>.** <table bo
2ea30 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72  rder="1">.** <tr
2ea40 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62  ><th> Internal<b
2ea50 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75  r>Type <th> Requ
2ea60 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74  ested<br>Type <t
2ea70 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a  h>  Conversion.*
2ea80 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  *.** <tr><td>  N
2ea90 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  ULL    <td> INTE
2eaa0 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  GER   <td> Resul
2eab0 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74  t is 0.** <tr><t
2eac0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2ead0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2eae0 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a  Result is 0.0.**
2eaf0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
2eb00 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
2eb10 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
2eb20 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
2eb30 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
2eb40 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  L    <td>   BLOB
2eb50 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
2eb60 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2eb70 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
2eb80 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f  TEGER  <td>  FLO
2eb90 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
2eba0 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20  rt from integer 
2ebb0 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  to float.** <tr>
2ebc0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
2ebd0 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
2ebe0 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
2ebf0 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72  g of the integer
2ec00 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
2ec10 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f  EGER  <td>   BLO
2ec20 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
2ec30 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a  s INTEGER->TEXT.
2ec40 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
2ec50 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  AT   <td> INTEGE
2ec60 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20  R   <td> [CAST] 
2ec70 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74  to INTEGER.** <t
2ec80 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
2ec90 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
2eca0 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
2ecb0 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74  ing of the float
2ecc0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
2ecd0 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  OAT   <td>   BLO
2ece0 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  B    <td> [CAST]
2ecf0 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e   to BLOB.** <tr>
2ed00 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
2ed10 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
2ed20 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45  > [CAST] to INTE
2ed30 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  GER.** <tr><td> 
2ed40 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46   TEXT    <td>  F
2ed50 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41  LOAT    <td> [CA
2ed60 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c  ST] to REAL.** <
2ed70 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
2ed80 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2ed90 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a  <td> No change.*
2eda0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
2edb0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
2edc0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
2edd0 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
2ede0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
2edf0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
2ee00 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41  d> [CAST] to REA
2ee10 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  L.** <tr><td>  B
2ee20 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45  LOB    <td>   TE
2ee30 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61  XT    <td> Add a
2ee40 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2ee50 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f   if needed.** </
2ee60 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63  table>.** </bloc
2ee70 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
2ee80 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20  The table above 
2ee90 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20  makes reference 
2eea0 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  to standard C li
2eeb0 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20  brary functions 
2eec0 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74  atoi().** and at
2eed0 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f  of().  SQLite do
2eee0 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73  es not really us
2eef0 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  e these function
2ef00 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a  s.  It has its.*
2ef10 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74  * own equivalent
2ef20 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e   internal routin
2ef30 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20  es.  The atoi() 
2ef40 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73  and atof() names
2ef50 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20   are.** used in 
2ef60 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72  the table for br
2ef70 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73  evity and becaus
2ef80 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c  e they are famil
2ef90 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43  iar to most.** C
2efa0 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a   programmers..**
2efb0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68  .** Note that wh
2efc0 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  en type conversi
2efd0 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74  ons occur, point
2efe0 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ers returned by 
2eff0 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  prior.** calls t
2f000 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2f010 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
2f020 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20  _column_text(), 
2f030 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  and/or.** sqlite
2f040 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2f050 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64  ) may be invalid
2f060 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f  ated..** Type co
2f070 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f  nversions and po
2f080 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69  inter invalidati
2f090 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  ons might occur.
2f0a0 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77  ** in the follow
2f0b0 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a  ing cases:.**.**
2f0c0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
2f0d0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
2f0e0 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20  t is a BLOB and 
2f0f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2f100 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  ext() or.**     
2f110 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f120 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
2f130 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d  ed.  A zero-term
2f140 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20  inator might.** 
2f150 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20       need to be 
2f160 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72  added to the str
2f170 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  ing.</li>.** <li
2f180 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
2f190 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74  ntent is UTF-8 t
2f1a0 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
2f1b0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2f1c0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
2f1d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2f1e0 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
2f1f0 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
2f200 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
2f210 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e        to UTF-16.
2f220 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
2f230 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
2f240 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74  t is UTF-16 text
2f250 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2f260 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
2f270 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
2f280 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20  olumn_text() is 
2f290 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
2f2a0 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
2f2b0 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
2f2c0 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a  o UTF-8.</li>.**
2f2d0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f   </ul>.**.** ^Co
2f2e0 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65  nversions betwee
2f2f0 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55  n UTF-16be and U
2f300 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61  TF-16le are alwa
2f310 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  ys done in place
2f320 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69   and do.** not i
2f330 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f  nvalidate a prio
2f340 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67  r pointer, thoug
2f350 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20  h of course the 
2f360 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62  content of the b
2f370 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68  uffer.** that th
2f380 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20  e prior pointer 
2f390 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20  references will 
2f3a0 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69  have been modifi
2f3b0 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73  ed.  Other kinds
2f3c0 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f  .** of conversio
2f3d0 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c  n are done in pl
2f3e0 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70  ace when it is p
2f3f0 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d  ossible, but som
2f400 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61  etimes they.** a
2f410 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  re not possible 
2f420 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73  and in those cas
2f430 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  es prior pointer
2f440 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65  s are invalidate
2f450 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66  d..**.** The saf
2f460 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20  est and easiest 
2f470 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69  to remember poli
2f480 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20  cy is to invoke 
2f490 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
2f4a0 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  * in one of the 
2f4b0 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a  following ways:.
2f4c0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c  **.** <ul>.**  <
2f4d0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
2f4e0 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65  n_text() followe
2f4f0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2f500 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
2f510 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
2f520 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
2f530 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
2f540 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2f550 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
2f560 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2f570 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20  xt16() followed 
2f580 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2f590 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e  n_bytes16()</li>
2f5a0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
2f5b0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
2f5c0 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20  you should call 
2f5d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2f5e0 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  ext(),.** sqlite
2f5f0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
2f600 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
2f610 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73  mn_text16() firs
2f620 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72  t to force the r
2f630 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68  esult.** into th
2f640 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74  e desired format
2f650 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71  , then invoke sq
2f660 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2f670 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  es() or.** sqlit
2f680 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2f690 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20  6() to find the 
2f6a0 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75  size of the resu
2f6b0 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20  lt.  Do not mix 
2f6c0 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69  calls.** to sqli
2f6d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2f6e0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
2f6f0 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20  umn_blob() with 
2f700 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
2f710 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2f720 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74  16(), and do not
2f730 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71   mix calls to sq
2f740 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2f750 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61  t16().** with ca
2f760 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2f770 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a  olumn_bytes()..*
2f780 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65  *.** ^The pointe
2f790 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  rs returned are 
2f7a0 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79  valid until a ty
2f7b0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  pe conversion oc
2f7c0 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72  curs as.** descr
2f7d0 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75  ibed above, or u
2f7e0 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ntil [sqlite3_st
2f7f0 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
2f800 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
2f810 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2f820 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e  ze()] is called.
2f830 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70    ^The memory sp
2f840 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  ace used to hold
2f850 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20   strings.** and 
2f860 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61  BLOBs is freed a
2f870 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44  utomatically.  D
2f880 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73  o <b>not</b> pas
2f890 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72  s the pointers r
2f8a0 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  eturned.** from 
2f8b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2f8c0 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
2f8d0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
2f8e0 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b  , etc. into.** [
2f8f0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
2f900 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65  .**.** ^(If a me
2f910 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2f920 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
2f930 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69  ing the evaluati
2f940 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  on of any.** of 
2f950 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20  these routines, 
2f960 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  a default value 
2f970 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
2f980 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a  e default value.
2f990 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65  ** is either the
2f9a0 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20   integer 0, the 
2f9b0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
2f9c0 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20  umber 0.0, or a 
2f9d0 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e  NULL.** pointer.
2f9e0 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c    Subsequent cal
2f9f0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
2fa00 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72  rrcode()] will r
2fa10 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
2fa20 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f  _NOMEM].)^.*/.co
2fa30 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2fa40 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71  3_column_blob(sq
2fa50 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2fa60 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
2fa70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2fa80 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2fa90 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
2faa0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2fab0 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74  tes16(sqlite3_st
2fac0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2fad0 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63  double sqlite3_c
2fae0 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c  olumn_double(sql
2faf0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2fb00 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
2fb10 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71  e3_column_int(sq
2fb20 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2fb30 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
2fb40 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f  int64 sqlite3_co
2fb50 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74  lumn_int64(sqlit
2fb60 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2fb70 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67  ol);.const unsig
2fb80 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
2fb90 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71  3_column_text(sq
2fba0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2fbb0 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f   iCol);.const vo
2fbc0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2fbd0 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  mn_text16(sqlite
2fbe0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2fbf0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
2fc00 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69  column_type(sqli
2fc10 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2fc20 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61  Col);.sqlite3_va
2fc30 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  lue *sqlite3_col
2fc40 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  umn_value(sqlite
2fc50 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2fc60 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
2fc70 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50  REF: Destroy A P
2fc80 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2fc90 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e  t Object.**.** ^
2fca0 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
2fcb0 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  lize() function 
2fcc0 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c  is called to del
2fcd0 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ete a [prepared 
2fce0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
2fcf0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
2fd00 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
2fd10 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65   the statement e
2fd20 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72  ncountered no er
2fd30 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68  rors.** or if th
2fd40 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
2fd50 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61  ever been evalua
2fd60 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ted, then sqlite
2fd70 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74  3_finalize() ret
2fd80 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  urns.** SQLITE_O
2fd90 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  K.  ^If the most
2fda0 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69   recent evaluati
2fdb0 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20  on of statement 
2fdc0 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a  S failed, then.*
2fdd0 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  * sqlite3_finali
2fde0 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68  ze(S) returns th
2fdf0 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  e appropriate [e
2fe00 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  rror code] or.**
2fe10 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
2fe20 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
2fe30 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
2fe40 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63  ize(S) routine c
2fe50 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20  an be called at 
2fe60 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67  any point during
2fe70 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63  .** the life cyc
2fe80 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  le of [prepared 
2fe90 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a  statement] S:.**
2fea0 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e   before statemen
2feb0 74 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c  t S is ever eval
2fec0 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20  uated, after.** 
2fed0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c  one or more call
2fee0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
2fef0 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72  set()], or after
2ff00 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20   any call.** to 
2ff10 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2ff20 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
2ff30 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
2ff40 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a  e statement has.
2ff50 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65  ** completed exe
2ff60 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  cution..**.** ^I
2ff70 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
2ff80 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20  finalize() on a 
2ff90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
2ffa0 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
2ffb0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
2ffc0 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e  ication must fin
2ffd0 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65  alize every [pre
2ffe0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2fff0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f   in order to avo
30000 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c  id.** resource l
30010 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67  eaks.  It is a g
30020 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f  rievous error fo
30030 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
30040 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a  n to try to use.
30050 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74  ** a prepared st
30060 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
30070 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
30080 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66  zed.  Any use of
30090 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73   a prepared.** s
300a0 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69  tatement after i
300b0 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
300c0 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20  ized can result 
300d0 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  in undefined and
300e0 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20  .** undesirable 
300f0 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73  behavior such as
30100 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68   segfaults and h
30110 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a  eap corruption..
30120 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66  */.int sqlite3_f
30130 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f  inalize(sqlite3_
30140 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
30150 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
30160 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20  eset A Prepared 
30170 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
30180 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
30190 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74  e3_reset() funct
301a0 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
301b0 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72   reset a [prepar
301c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
301d0 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20   object back to 
301e0 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
301f0 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72  e, ready to be r
30200 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e  e-executed..** ^
30210 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  Any SQL statemen
30220 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74  t variables that
30230 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e   had values boun
30240 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a  d to them using.
30250 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
30260 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  bind_blob | sqli
30270 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49  te3_bind_*() API
30280 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76  ] retain their v
30290 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73  alues..** Use [s
302a0 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
302b0 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65  dings()] to rese
302c0 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a  t the bindings..
302d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
302e0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
302f0 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74  terface resets t
30300 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
30310 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63  tement] S.** bac
30320 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  k to the beginni
30330 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61  ng of its progra
30340 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  m..**.** ^If the
30350 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
30360 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
30370 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
30380 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
30390 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65  ement] S returne
303a0 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f  d [SQLITE_ROW] o
303b0 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  r [SQLITE_DONE],
303c0 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74  .** or if [sqlit
303d0 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20  e3_step(S)] has 
303e0 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65  never before bee
303f0 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a  n called on S,.*
30400 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  * then [sqlite3_
30410 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
30420 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
30430 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
30440 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
30450 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
30460 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
30470 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30480 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61  t] S indicated a
30490 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a  n error, then.**
304a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
304b0 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61  S)] returns an a
304c0 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
304d0 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  r code]..**.** ^
304e0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
304f0 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
30500 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
30510 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f   the values.** o
30520 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62  f any [sqlite3_b
30530 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67  ind_blob|binding
30540 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61  s] on the [prepa
30550 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
30560 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
30570 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73  _reset(sqlite3_s
30580 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
30590 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72  .** CAPI3REF: Cr
305a0 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65  eate Or Redefine
305b0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   SQL Functions.*
305c0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e  * KEYWORDS: {fun
305d0 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
305e0 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57  outines}.** KEYW
305f0 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
30600 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
30610 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57  unction}.** KEYW
30620 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
30630 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
30640 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  unctions}.**.** 
30650 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
30660 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b   (collectively k
30670 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f  nown as "functio
30680 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
30690 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65  nes").** are use
306a0 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e  d to add SQL fun
306b0 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
306c0 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66  ates or to redef
306d0 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  ine the behavior
306e0 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20  .** of existing 
306f0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
30700 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68   aggregates.  Th
30710 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63  e only differenc
30720 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  es between.** th
30730 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
30740 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69   the text encodi
30750 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a  ng expected for.
30760 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  ** the second pa
30770 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d  rameter (the nam
30780 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  e of the functio
30790 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29  n being created)
307a0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73  .** and the pres
307b0 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20  ence or absence 
307c0 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  of a destructor 
307d0 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20  callback for.** 
307e0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
307f0 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  data pointer..**
30800 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70  .** ^The first p
30810 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
30820 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
30830 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74  tion] to which t
30840 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69  he SQL.** functi
30850 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65  on is to be adde
30860 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69  d.  ^If an appli
30870 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65  cation uses more
30880 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61   than one databa
30890 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
308a0 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f   then applicatio
308b0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
308c0 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20  nctions must be 
308d0 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68  added.** to each
308e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
308f0 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e  tion separately.
30900 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
30910 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
30920 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
30930 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
30940 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a  be created or.**
30950 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   redefined.  ^Th
30960 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
30970 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20  name is limited 
30980 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20  to 255 bytes in 
30990 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65  a UTF-8.** repre
309a0 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75  sentation, exclu
309b0 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f  sive of the zero
309c0 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e  -terminator.  ^N
309d0 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d  ote that the nam
309e0 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69  e.** length limi
309f0 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79  t is in UTF-8 by
30a00 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74  tes, not charact
30a10 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62  ers nor UTF-16 b
30a20 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20  ytes.  .** ^Any 
30a30 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74  attempt to creat
30a40 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  e a function wit
30a50 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a  h a longer name.
30a60 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69  ** will result i
30a70 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
30a80 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64  ] being returned
30a90 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
30aa0 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41  rd parameter (nA
30ab0 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75  rg).** is the nu
30ac0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
30ad0 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66  s that the SQL f
30ae0 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
30af0 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e  gregate takes. ^
30b00 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  If this paramete
30b10 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68  r is -1, then th
30b20 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
30b30 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d  r.** aggregate m
30b40 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62  ay take any numb
30b50 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
30b60 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
30b70 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62  e limit.** set b
30b80 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  y [sqlite3_limit
30b90 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ]([SQLITE_LIMIT_
30ba0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20  FUNCTION_ARG]). 
30bb0 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   If the third.**
30bc0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65   parameter is le
30bd0 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72  ss than -1 or gr
30be0 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74  eater than 127 t
30bf0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
30c00 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64   is.** undefined
30c10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
30c20 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65  rth parameter, e
30c30 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69  TextRep, specifi
30c40 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49  es what.** [SQLI
30c50 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65  TE_UTF8 | text e
30c60 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51  ncoding] this SQ
30c70 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65  L function prefe
30c80 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61  rs for.** its pa
30c90 72 61 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61  rameters.  The a
30ca0 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
30cb0 64 20 73 65 74 20 74 68 69 73 20 70 61 72 61 6d  d set this param
30cc0 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49  eter to.** [SQLI
30cd0 54 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74  TE_UTF16LE] if t
30ce0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  he function impl
30cf0 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b  ementation invok
30d00 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  es .** [sqlite3_
30d10 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29  value_text16le()
30d20 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f  ] on an input, o
30d30 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  r [SQLITE_UTF16B
30d40 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70  E] if the.** imp
30d50 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f  lementation invo
30d60 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  kes [sqlite3_val
30d70 75 65 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f  ue_text16be()] o
30d80 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a  n an input, or.*
30d90 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  * [SQLITE_UTF16]
30da0 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   if [sqlite3_val
30db0 75 65 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20  ue_text16()] is 
30dc0 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  used, or [SQLITE
30dd0 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77  _UTF8].** otherw
30de0 69 73 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20  ise.  ^The same 
30df0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  SQL function may
30e00 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d   be registered m
30e10 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73  ultiple times us
30e20 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74  ing.** different
30e30 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
30e40 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20  encodings, with 
30e50 64 69 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d  different implem
30e60 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a  entations for.**
30e70 20 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a   each encoding..
30e80 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c  ** ^When multipl
30e90 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
30ea0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
30eb0 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c  nction are avail
30ec0 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  able, SQLite.** 
30ed0 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e  will pick the on
30ee0 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20  e that involves 
30ef0 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
30f00 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73   of data convers
30f10 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
30f20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
30f30 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20   may optionally 
30f40 62 65 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51  be ORed with [SQ
30f50 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54  LITE_DETERMINIST
30f60 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  IC].** to signal
30f70 20 74 68 61 74 20 74 68 65 20 66 75 6e 63 74 69   that the functi
30f80 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72  on will always r
30f90 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72  eturn the same r
30fa0 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74  esult given.** t
30fb0 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77  he same inputs w
30fc0 69 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53  ithin a single S
30fd0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d  QL statement.  M
30fe0 6f 73 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ost SQL function
30ff0 73 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69  s are.** determi
31000 6e 69 73 74 69 63 2e 20 20 54 68 65 20 62 75 69  nistic.  The bui
31010 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d  lt-in [random()]
31020 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
31030 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61   an example of a
31040 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  .** function tha
31050 74 20 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69  t is not determi
31060 6e 69 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c  nistic.  The SQL
31070 69 74 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65  ite query planne
31080 72 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20  r is able to.** 
31090 70 65 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e  perform addition
310a0 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73  al optimizations
310b0 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69   on deterministi
310c0 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20  c functions, so 
310d0 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53  use.** of the [S
310e0 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53  QLITE_DETERMINIS
310f0 54 49 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63  TIC] flag is rec
31100 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70  ommended where p
31110 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ossible..**.** ^
31120 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d  (The fifth param
31130 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74  eter is an arbit
31140 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54  rary pointer.  T
31150 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
31160 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63  n of the.** func
31170 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63  tion can gain ac
31180 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69  cess to this poi
31190 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69  nter using [sqli
311a0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
311b0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
311c0 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e  ixth, seventh an
311d0 64 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74  d eighth paramet
311e0 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65  ers, xFunc, xSte
311f0 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72  p and xFinal, ar
31200 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f  e.** pointers to
31210 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63   C-language func
31220 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65  tions that imple
31230 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
31240 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
31250 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72  egate. ^A scalar
31260 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
31270 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
31280 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  entation of the 
31290 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63  xFunc.** callbac
312a0 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69  k only; NULL poi
312b0 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61  nters must be pa
312c0 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65  ssed as the xSte
312d0 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20  p and xFinal.** 
312e0 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20  parameters. ^An 
312f0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
31300 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
31310 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
31320 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e  n of xStep.** an
31330 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c  d xFinal and NUL
31340 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62  L pointer must b
31350 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75  e passed for xFu
31360 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61  nc. ^To delete a
31370 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51  n existing.** SQ
31380 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  L function or ag
31390 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55  gregate, pass NU
313a0 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20  LL pointers for 
313b0 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69  all three functi
313c0 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e  on.** callbacks.
313d0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20  .**.** ^(If the 
313e0 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20  ninth parameter 
313f0 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
31400 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20  e_function_v2() 
31410 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20  is not NULL,.** 
31420 74 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72  then it is destr
31430 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70  uctor for the ap
31440 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
31450 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20  ointer. .** The 
31460 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e  destructor is in
31470 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66  voked when the f
31480 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74  unction is delet
31490 65 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65  ed, either by be
314a0 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65  ing.** overloade
314b0 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61  d or when the da
314c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
314d0 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e  n closes.)^.** ^
314e0 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
314f0 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69  s also invoked i
31500 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a  f the call to.**
31510 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
31520 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61  function_v2() fa
31530 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  ils..** ^When th
31540 65 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c  e destructor cal
31550 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e  lback of the ten
31560 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
31570 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69  invoked, it.** i
31580 73 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c  s passed a singl
31590 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
315a0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
315b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
315c0 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77  ta .** pointer w
315d0 68 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66  hich was the fif
315e0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
315f0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
31600 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a  unction_v2()..**
31610 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69  .** ^It is permi
31620 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  tted to register
31630 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
31640 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
31650 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f   same.** functio
31660 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ns with the same
31670 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65   name but with e
31680 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20  ither differing 
31690 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72  numbers of.** ar
316a0 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65  guments or diffe
316b0 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74  ring preferred t
316c0 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20  ext encodings.  
316d0 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
316e0 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  .** the implemen
316f0 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74  tation that most
31700 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73   closely matches
31710 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63   the way in whic
31720 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e  h the.** SQL fun
31730 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20  ction is used.  
31740 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  ^A function impl
31750 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20  ementation with 
31760 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a  a non-negative.*
31770 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72  * nArg parameter
31780 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74   is a better mat
31790 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
317a0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
317b0 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61  n with.** a nega
317c0 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66  tive nArg.  ^A f
317d0 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
317e0 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  e preferred text
317f0 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74   encoding.** mat
31800 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73  ches the databas
31810 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20  e encoding is a 
31820 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20  better.** match 
31830 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
31840 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
31850 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e  ng is different.
31860 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f    .** ^A functio
31870 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
31880 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
31890 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36  is between UTF16
318a0 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a  le and UTF16be.*
318b0 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61  * is a closer ma
318c0 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
318d0 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
318e0 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
318f0 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  e is.** between 
31900 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a  UTF8 and UTF16..
31910 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20  **.** ^Built-in 
31920 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
31930 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e   overloaded by n
31940 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  ew application-d
31950 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73  efined functions
31960 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c  ..**.** ^An appl
31970 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
31980 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  function is perm
31990 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74  itted to call ot
319a0 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
319b0 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76  terfaces.  Howev
319c0 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d  er, such calls m
319d0 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65  ust not.** close
319e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
319f0 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e  nnection nor fin
31a00 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74  alize or reset t
31a10 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73  he prepared.** s
31a20 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63  tatement in whic
31a30 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  h the function i
31a40 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e  s running..*/.in
31a50 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
31a60 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c  _function(.  sql
31a70 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
31a80 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
31a90 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
31aa0 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
31ab0 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
31ac0 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
31ad0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
31ae0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
31af0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
31b00 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
31b10 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
31b20 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
31b30 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
31b40 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31b50 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
31b60 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
31b70 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
31b80 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  b,.  const void 
31b90 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
31ba0 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
31bb0 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
31bc0 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
31bd0 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
31be0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
31bf0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
31c00 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
31c10 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
31c20 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
31c30 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
31c40 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
31c50 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e  _context*).);.in
31c60 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
31c70 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20  _function_v2(.  
31c80 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
31c90 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
31ca0 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
31cb0 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
31cc0 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
31cd0 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
31ce0 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
31cf0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
31d00 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
31d10 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
31d20 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
31d30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
31d40 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
31d50 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
31d60 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  xt*),.  void(*xD
31d70 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
31d80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31d90 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67  F: Text Encoding
31da0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
31db0 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e  nstant define in
31dc0 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74  teger codes that
31dd0 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76   represent the v
31de0 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65  arious.** text e
31df0 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74  ncodings support
31e00 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f  ed by SQLite..*/
31e10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
31e20 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31  UTF8           1
31e30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
31e40 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32  UTF16LE        2
31e50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
31e60 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33  UTF16BE        3
31e70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
31e80 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34  UTF16          4
31e90 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76      /* Use nativ
31ea0 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a  e byte order */.
31eb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
31ec0 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20  NY            5 
31ed0 20 20 20 2f 2a 20 44 65 70 72 65 63 61 74 65 64     /* Deprecated
31ee0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
31ef0 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
31f00 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    8    /* sqlite
31f10 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
31f20 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a  on only */../*.*
31f30 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63  * CAPI3REF: Func
31f40 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  tion Flags.**.**
31f50 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
31f60 20 6d 61 79 20 62 65 20 4f 52 65 64 20 74 6f 67   may be ORed tog
31f70 65 74 68 65 72 20 77 69 74 68 20 74 68 65 20 0a  ether with the .
31f80 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20  ** [SQLITE_UTF8 
31f90 7c 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  | preferred text
31fa0 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20 74 68   encoding] as th
31fb0 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
31fc0 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  t.** to [sqlite3
31fd0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
31fe0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
31ff0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
32000 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
32010 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
32020 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65  on_v2()]..*/.#de
32030 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 45  fine SQLITE_DETE
32040 52 4d 49 4e 49 53 54 49 43 20 20 20 20 30 78 38  RMINISTIC    0x8
32050 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  00../*.** CAPI3R
32060 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46  EF: Deprecated F
32070 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52  unctions.** DEPR
32080 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65  ECATED.**.** The
32090 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
320a0 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20   [deprecated].  
320b0 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e  In order to main
320c0 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64  tain.** backward
320d0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
320e0 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c  with older code,
320f0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
32100 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f   continue .** to
32110 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20   be supported.  
32120 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70  However, new app
32130 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
32140 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73   avoid.** the us
32150 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  e of these funct
32160 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65  ions.  To help e
32170 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20  ncourage people 
32180 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e  to avoid.** usin
32190 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  g these function
321a0 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f  s, we are not go
321b0 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20  ing to tell you 
321c0 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f  what they do..*/
321d0 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
321e0 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a  OMIT_DEPRECATED.
321f0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
32200 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67  D int sqlite3_ag
32210 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71  gregate_count(sq
32220 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
32230 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
32240 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  ED int sqlite3_e
32250 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73  xpired(sqlite3_s
32260 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  tmt*);.SQLITE_DE
32270 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
32280 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69  ite3_transfer_bi
32290 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
322a0 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74  tmt*, sqlite3_st
322b0 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
322c0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
322d0 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76  te3_global_recov
322e0 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  er(void);.SQLITE
322f0 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64  _DEPRECATED void
32300 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f   sqlite3_thread_
32310 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53  cleanup(void);.S
32320 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
32330 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d   int sqlite3_mem
32340 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a  ory_alarm(void(*
32350 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  )(void*,sqlite3_
32360 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20  int64,int),.    
32370 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
32380 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f    void*,sqlite3_
32390 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a  int64);.#endif..
323a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
323b0 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75  Obtaining SQL Fu
323c0 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72  nction Parameter
323d0 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68   Values.**.** Th
323e0 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70  e C-language imp
323f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53  lementation of S
32400 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
32410 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73   aggregates uses
32420 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20  .** this set of 
32430 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e  interface routin
32440 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  es to access the
32450 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65   parameter value
32460 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63  s on.** the func
32470 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
32480 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75  e..**.** The xFu
32490 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66  nc (for scalar f
324a0 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74  unctions) or xSt
324b0 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74  ep (for aggregat
324c0 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  es) parameters.*
324d0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
324e0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
324f0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
32500 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
32510 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c  )].** define cal
32520 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c  lbacks that impl
32530 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
32540 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
32550 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33  egates..** The 3
32560 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
32570 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20  these callbacks 
32580 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
32590 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70  ointers to.** [p
325a0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
325b0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
325c0 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b    There is one [
325d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
325e0 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63  bject for.** eac
325f0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
32600 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  he SQL function.
32610 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
32620 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20   are used to.** 
32630 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66  extract values f
32640 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
32650 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
32660 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
32670 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20  tines work only 
32680 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20  with [protected 
32690 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
326a0 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61  bjects..** Any a
326b0 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
326c0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20  ese routines on 
326d0 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  an [unprotected 
326e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
326f0 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73  * object results
32700 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
32710 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  havior..**.** ^T
32720 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
32730 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65  rk just like the
32740 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b   corresponding [
32750 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
32760 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65  nctions].** exce
32770 70 74 20 74 68 61 74 20 74 68 65 73 65 20 72 6f  pt that these ro
32780 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69  utines take a si
32790 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20  ngle [protected 
327a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
327b0 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72  bject.** pointer
327c0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73   instead of a [s
327d0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f  qlite3_stmt*] po
327e0 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74  inter and an int
327f0 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  eger column numb
32800 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
32810 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
32820 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20  t16() interface 
32830 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31  extracts a UTF-1
32840 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74  6 string.** in t
32850 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f  he native byte-o
32860 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74  rder of the host
32870 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a   machine.  ^The.
32880 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
32890 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20  _text16be() and 
328a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
328b0 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61  xt16le() interfa
328c0 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55  ces.** extract U
328d0 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73  TF-16 strings as
328e0 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20   big-endian and 
328f0 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65  little-endian re
32900 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
32910 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
32920 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
32930 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  pe() interface a
32940 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79  ttempts to apply
32950 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69  .** numeric affi
32960 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75  nity to the valu
32970 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74  e.  This means t
32980 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69  hat an attempt i
32990 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e  s.** made to con
329a0 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74  vert the value t
329b0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20  o an integer or 
329c0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20  floating point. 
329d0 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f   If.** such a co
329e0 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73  nversion is poss
329f0 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73  ible without los
32a00 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  s of information
32a10 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f   (in other.** wo
32a20 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75  rds, if the valu
32a30 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68  e is a string th
32a40 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20  at looks like a 
32a50 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20  number).** then 
32a60 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  the conversion i
32a70 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74  s performed.  Ot
32a80 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65  herwise no conve
32a90 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a  rsion occurs..**
32aa0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54   The [SQLITE_INT
32ab0 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d  EGER | datatype]
32ac0 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f   after conversio
32ad0 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
32ae0 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61  .**.** Please pa
32af0 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74  y particular att
32b00 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61  ention to the fa
32b10 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e  ct that the poin
32b20 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ter returned.** 
32b30 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
32b40 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  lue_blob()], [sq
32b50 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
32b60 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
32b70 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
32b80 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c  ()] can be inval
32b90 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73  idated by a subs
32ba0 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  equent call to.*
32bb0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
32bc0 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69  _bytes()], [sqli
32bd0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
32be0 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  6()], [sqlite3_v
32bf0 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
32c00 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
32c10 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a  ue_text16()]..**
32c20 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
32c30 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
32c40 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
32c50 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65  thread as.** the
32c60 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68   SQL function th
32c70 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20  at supplied the 
32c80 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d  [sqlite3_value*]
32c90 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a   parameters..*/.
32ca0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
32cb0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73  te3_value_blob(s
32cc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
32cd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
32ce0 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  e_bytes(sqlite3_
32cf0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
32d00 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
32d10 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
32d20 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  *);.double sqlit
32d30 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28  e3_value_double(
32d40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
32d50 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
32d60 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76  ue_int(sqlite3_v
32d70 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f  alue*);.sqlite3_
32d80 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61  int64 sqlite3_va
32d90 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  lue_int64(sqlite
32da0 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
32db0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
32dc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
32dd0 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  xt(sqlite3_value
32de0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
32df0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
32e00 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  xt16(sqlite3_val
32e10 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
32e20 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
32e30 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
32e40 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
32e50 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
32e60 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c  lue_text16be(sql
32e70 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
32e80 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
32e90 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
32ea0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
32eb0 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
32ec0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
32ed0 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
32ee0 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67  I3REF: Obtain Ag
32ef0 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e  gregate Function
32f00 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49   Context.**.** I
32f10 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
32f20 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  f aggregate SQL 
32f30 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68  functions use th
32f40 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f  is.** routine to
32f50 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
32f60 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65   for storing the
32f70 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ir state..**.** 
32f80 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20  ^The first time 
32f90 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  the sqlite3_aggr
32fa0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
32fb0 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  N) routine is ca
32fc0 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70  lled .** for a p
32fd0 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67  articular aggreg
32fe0 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51  ate function, SQ
32ff0 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  Lite.** allocate
33000 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a  s N of memory, z
33010 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d  eroes out that m
33020 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72  emory, and retur
33030 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  ns a pointer.** 
33040 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72  to the new memor
33050 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e  y. ^On second an
33060 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  d subsequent cal
33070 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
33080 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
33090 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d  xt() for the sam
330a0 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
330b0 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a  tion instance,.*
330c0 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65  * the same buffe
330d0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  r is returned.  
330e0 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  Sqlite3_aggregat
330f0 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e  e_context() is n
33100 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  ormally.** calle
33110 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
33120 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68  invocation of th
33130 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b  e xStep callback
33140 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a   and then one.**
33150 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20   last time when 
33160 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62  the xFinal callb
33170 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ack is invoked. 
33180 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20   ^(When no rows 
33190 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72  match.** an aggr
331a0 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65  egate query, the
331b0 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63   xStep() callbac
331c0 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61  k of the aggrega
331d0 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69  te function.** i
331e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
331f0 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e   never called an
33200 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61  d xFinal() is ca
33210 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63  lled exactly onc
33220 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63  e..** In those c
33230 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67  ases, sqlite3_ag
33240 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
33250 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65  ) might be calle
33260 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72  d for the.** fir
33270 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74  st time from wit
33280 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a  hin xFinal().)^.
33290 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
332a0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
332b0 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
332c0 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  e returns a NULL
332d0 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65   pointer .** whe
332e0 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20 69  n first called i
332f0 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
33300 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
33310 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79  o or if a memory
33320 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72 72  .** allocate err
33330 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a  or occurs..**.**
33340 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66   ^(The amount of
33350 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64   space allocated
33360 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72   by sqlite3_aggr
33370 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
33380 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69  N) is.** determi
33390 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72  ned by the N par
333a0 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20  ameter on first 
333b0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e  successful call.
333c0 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a    Changing the.*
333d0 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20  * value of N in 
333e0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
333f0 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  to sqlite3_aggre
33400 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77  gate_context() w
33410 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d  ithin.** the sam
33420 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
33430 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69  tion instance wi
33440 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68  ll not resize th
33450 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
33460 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69  cation.)^  Withi
33470 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c  n the xFinal cal
33480 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75 73  lback, it is cus
33490 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a  tomary to set.**
334a0 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f   N=0 in calls to
334b0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
334c0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
334d0 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70  so that no .** p
334e0 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20  ointless memory 
334f0 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75  allocations occu
33500 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  r..**.** ^SQLite
33510 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66   automatically f
33520 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  rees the memory 
33530 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a  allocated by .**
33540 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
33550 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65  te_context() whe
33560 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  n the aggregate 
33570 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e  query concludes.
33580 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
33590 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
335a0 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  be a copy of the
335b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
335c0 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74  text | SQL funct
335d0 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61  ion context] tha
335e0 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  t is the first p
335f0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
33600 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e  he xStep or xFin
33610 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74  al callback rout
33620 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ine that impleme
33630 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74  nts the aggregat
33640 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  e.** function..*
33650 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
33660 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
33670 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
33680 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
33690 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  * the aggregate 
336a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
336b0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
336c0 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   *sqlite3_aggreg
336d0 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69  ate_context(sqli
336e0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
336f0 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a  t nBytes);../*.*
33700 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72  * CAPI3REF: User
33710 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69   Data For Functi
33720 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ons.**.** ^The s
33730 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
33740 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
33750 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
33760 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68  * the pointer th
33770 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72  at was the pUser
33780 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28  Data parameter (
33790 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
337a0 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
337b0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
337c0 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
337d0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
337e0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
337f0 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
33800 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
33810 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
33820 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
33830 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
33840 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
33850 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
33860 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
33870 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70   which.** the ap
33880 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
33890 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  d function is ru
338a0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
338b0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
338c0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
338d0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
338e0 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
338f0 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75  onnection For Fu
33900 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54  nctions.**.** ^T
33910 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  he sqlite3_conte
33920 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69  xt_db_handle() i
33930 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
33940 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
33950 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
33960 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
33970 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20  ction] (the 1st 
33980 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
33990 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
339a0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
339b0 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
339c0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
339d0 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
339e0 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
339f0 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
33a00 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
33a10 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
33a20 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74  /.sqlite3 *sqlit
33a30 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
33a40 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ndle(sqlite3_con
33a50 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
33a60 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f  API3REF: Functio
33a70 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61  n Auxiliary Data
33a80 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
33a90 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73  ctions may be us
33aa0 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65  ed by (non-aggre
33ab0 67 61 74 65 29 20 53 51 4c 20 66 75 6e 63 74 69  gate) SQL functi
33ac0 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69  ons to.** associ
33ad0 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74  ate metadata wit
33ae0 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65  h argument value
33af0 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76  s. If the same v
33b00 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74  alue is passed t
33b10 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e  o.** multiple in
33b20 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
33b30 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69   same SQL functi
33b40 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20  on during query 
33b50 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72  execution, under
33b60 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73  .** some circums
33b70 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63  tances the assoc
33b80 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d  iated metadata m
33b90 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e  ay be preserved.
33ba0 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20    An example.** 
33bb0 6f 66 20 77 68 65 72 65 20 74 68 69 73 20 6d 69  of where this mi
33bc0 67 68 74 20 62 65 20 75 73 65 66 75 6c 20 69 73  ght be useful is
33bd0 20 69 6e 20 61 20 72 65 67 75 6c 61 72 2d 65 78   in a regular-ex
33be0 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e  pression matchin
33bf0 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54  g.** function. T
33c00 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73  he compiled vers
33c10 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c  ion of the regul
33c20 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  ar expression ca
33c30 6e 20 62 65 20 73 74 6f 72 65 64 20 61 73 0a 2a  n be stored as.*
33c40 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  * metadata assoc
33c50 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 70  iated with the p
33c60 61 74 74 65 72 6e 20 73 74 72 69 6e 67 2e 20 20  attern string.  
33c70 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e 67  .** Then as long
33c80 20 61 73 20 74 68 65 20 70 61 74 74 65 72 6e 20   as the pattern 
33c90 73 74 72 69 6e 67 20 72 65 6d 61 69 6e 73 20 74  string remains t
33ca0 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 20  he same,.** the 
33cb0 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72  compiled regular
33cc0 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
33cd0 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c  be reused on mul
33ce0 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  tiple.** invocat
33cf0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
33d00 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
33d10 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
33d20 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
33d30 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
33d40 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
33d50 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63  etadata.** assoc
33d60 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  iated by the sql
33d70 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
33d80 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  () function with
33d90 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e   the Nth argumen
33da0 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68  t.** value to th
33db0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
33dc0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
33dd0 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ^If there is no 
33de0 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f  metadata.** asso
33df0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
33e00 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
33e10 74 2c 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f  t, this sqlite3_
33e20 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
33e30 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72  terface.** retur
33e40 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
33e50 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
33e60 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
33e70 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 72  a(C,N,P,X) inter
33e80 66 61 63 65 20 73 61 76 65 73 20 50 20 61 73 20  face saves P as 
33e90 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65  metadata for the
33ea0 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e   N-th.** argumen
33eb0 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
33ec0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
33ed0 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71 75  ction.  ^Subsequ
33ee0 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
33ef0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
33f00 61 74 61 28 43 2c 4e 29 20 72 65 74 75 72 6e 20  ata(C,N) return 
33f10 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74 20  P from the most 
33f20 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74 65  recent.** sqlite
33f30 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
33f40 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69 66 20 74  N,P,X) call if t
33f50 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 73  he metadata is s
33f60 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a 2a  till valid or.**
33f70 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 6d 65 74   NULL if the met
33f80 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 64  adata has been d
33f90 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41 66  iscarded..** ^Af
33fa0 74 65 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f  ter each call to
33fb0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
33fc0 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77 68  data(C,N,P,X) wh
33fd0 65 72 65 20 58 20 69 73 20 6e 6f 74 20 4e 55 4c  ere X is not NUL
33fe0 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  L,.** SQLite wil
33ff0 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
34000 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e  tructor function
34010 20 58 20 77 69 74 68 20 70 61 72 61 6d 65 74 65   X with paramete
34020 72 20 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20 6f  r P exactly.** o
34030 6e 63 65 2c 20 77 68 65 6e 20 74 68 65 20 6d 65  nce, when the me
34040 74 61 64 61 74 61 20 69 73 20 64 69 73 63 61 72  tadata is discar
34050 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ded..** SQLite i
34060 73 20 66 72 65 65 20 74 6f 20 64 69 73 63 61 72  s free to discar
34070 64 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 61  d the metadata a
34080 74 20 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63 6c  t any time, incl
34090 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c  uding: <ul>.** <
340a0 6c 69 3e 20 77 68 65 6e 20 74 68 65 20 63 6f 72  li> when the cor
340b0 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74  responding funct
340c0 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68  ion parameter ch
340d0 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  anges, or.** <li
340e0 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  > when [sqlite3_
340f0 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
34100 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
34110 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 74   is called for t
34120 68 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20 73  he.**      SQL s
34130 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20  tatement, or.** 
34140 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c 69 74 65  <li> when sqlite
34150 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
34160 69 73 20 69 6e 76 6f 6b 65 64 20 61 67 61 69 6e  is invoked again
34170 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 70 61 72   on the same par
34180 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c  ameter, or.** <l
34190 69 3e 20 64 75 72 69 6e 67 20 74 68 65 20 6f 72  i> during the or
341a0 69 67 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f 73  iginal sqlite3_s
341b0 65 74 5f 61 75 78 64 61 74 61 28 29 20 63 61 6c  et_auxdata() cal
341c0 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79 20  l when a memory 
341d0 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61 74  .**      allocat
341e0 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
341f0 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  . </ul>)^.**.** 
34200 4e 6f 74 65 20 74 68 65 20 6c 61 73 74 20 62 75  Note the last bu
34210 6c 6c 65 74 20 69 6e 20 70 61 72 74 69 63 75 6c  llet in particul
34220 61 72 2e 20 20 54 68 65 20 64 65 73 74 72 75 63  ar.  The destruc
34230 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71 6c  tor X in .** sql
34240 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
34250 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74 20  (C,N,P,X) might 
34260 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64 69  be called immedi
34270 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 68  ately, before th
34280 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74  e.** sqlite3_set
34290 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
342a0 66 61 63 65 20 65 76 65 6e 20 72 65 74 75 72 6e  face even return
342b0 73 2e 20 20 48 65 6e 63 65 20 73 71 6c 69 74 65  s.  Hence sqlite
342c0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 0a  3_set_auxdata().
342d0 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 63 61 6c  ** should be cal
342e0 6c 65 64 20 6e 65 61 72 20 74 68 65 20 65 6e 64  led near the end
342f0 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
34300 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
34310 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74  and the.** funct
34320 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
34330 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61  on should not ma
34340 6b 65 20 61 6e 79 20 75 73 65 20 6f 66 20 50 20  ke any use of P 
34350 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65 33  after.** sqlite3
34360 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 68  _set_auxdata() h
34370 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a  as been called..
34380 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74  **.** ^(In pract
34390 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73  ice, metadata is
343a0 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65   preserved betwe
343b0 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  en function call
343c0 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  s for.** functio
343d0 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61  n parameters tha
343e0 74 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74 69  t are compile-ti
343f0 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69 6e  me constants, in
34400 63 6c 75 64 69 6e 67 20 6c 69 74 65 72 61 6c 0a  cluding literal.
34410 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70  ** values and [p
34420 61 72 61 6d 65 74 65 72 73 5d 20 61 6e 64 20 65  arameters] and e
34430 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70 6f  xpressions compo
34440 73 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  sed from the sam
34450 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  e.)^.**.** These
34460 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
34470 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
34480 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
34490 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
344a0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
344b0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
344c0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
344d0 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
344e0 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f  ext*, int N);.vo
344f0 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  id sqlite3_set_a
34500 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
34510 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20  ontext*, int N, 
34520 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28  void*, void (*)(
34530 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  void*));.../*.**
34540 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74   CAPI3REF: Const
34550 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70  ants Defining Sp
34560 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72  ecial Destructor
34570 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20   Behavior.**.** 
34580 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61  These are specia
34590 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65  l values for the
345a0 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74   destructor that
345b0 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73   is passed in as
345c0 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72   the.** final ar
345d0 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e  gument to routin
345e0 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
345f0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e  _result_blob()].
34600 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75    ^If the destru
34610 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ctor.** argument
34620 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49   is SQLITE_STATI
34630 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  C, it means that
34640 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69   the content poi
34650 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74  nter is constant
34660 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76  .** and will nev
34670 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64  er change.  It d
34680 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
34690 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e  be destroyed.  ^
346a0 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52  The.** SQLITE_TR
346b0 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65  ANSIENT value me
346c0 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
346d0 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  tent will likely
346e0 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68   change in.** th
346f0 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e  e near future an
34700 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68  d that SQLite sh
34710 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77  ould make its ow
34720 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
34730 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
34740 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
34750 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70  g..**.** The typ
34760 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72  edef is necessar
34770 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  y to work around
34780 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72   problems in cer
34790 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70  tain.** C++ comp
347a0 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  ilers..*/.typede
347b0 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
347c0 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
347d0 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e  )(void*);.#defin
347e0 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20  e SQLITE_STATIC 
347f0 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64       ((sqlite3_d
34800 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30  estructor_type)0
34810 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
34820 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73  _TRANSIENT   ((s
34830 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
34840 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a  r_type)-1)../*.*
34850 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74  * CAPI3REF: Sett
34860 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f  ing The Result O
34870 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f  f An SQL Functio
34880 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  n.**.** These ro
34890 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
348a0 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20  by the xFunc or 
348b0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73  xFinal callbacks
348c0 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65   that.** impleme
348d0 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  nt SQL functions
348e0 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
348f0 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    See.** [sqlite
34900 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
34910 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
34920 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
34930 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64  n16()].** for ad
34940 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
34950 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion..**.** Thes
34960 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b  e functions work
34970 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20   very much like 
34980 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62  the [parameter b
34990 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f  inding] family o
349a0 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75  f.** functions u
349b0 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75  sed to bind valu
349c0 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d  es to host param
349d0 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65  eters in prepare
349e0 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  d statements..**
349f0 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53   Refer to the [S
34a00 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f  QL parameter] do
34a10 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
34a20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
34a30 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  mation..**.** ^T
34a40 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
34a50 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  t_blob() interfa
34a60 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
34a70 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
34a80 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
34a90 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
34aa0 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20   the BLOB whose 
34ab0 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74  content is point
34ac0 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20  ed.** to by the 
34ad0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
34ae0 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20   and which is N 
34af0 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65  bytes long where
34b00 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69   N is the.** thi
34b10 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
34b20 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34b30 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
34b40 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65  () interfaces se
34b50 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  t the result of.
34b60 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
34b70 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
34b80 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42  ion to be a BLOB
34b90 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20   containing all 
34ba0 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e  zero.** bytes an
34bb0 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  d N bytes in siz
34bc0 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  e, where N is th
34bd0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32  e value of the 2
34be0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  nd parameter..**
34bf0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34c00 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29  _result_double()
34c10 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
34c20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
34c30 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
34c40 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
34c50 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74  on to be a float
34c60 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20  ing point value 
34c70 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
34c80 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  its 2nd argument
34c90 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
34ca0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
34cb0 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
34cc0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
34cd0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61   functions.** ca
34ce0 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  use the implemen
34cf0 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ted SQL function
34d00 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63   to throw an exc
34d10 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69  eption..** ^SQLi
34d20 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69  te uses the stri
34d30 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ng pointed to by
34d40 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61   the.** 2nd para
34d50 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
34d60 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
34d70 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
34d80 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61  t_error16().** a
34d90 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e  s the text of an
34da0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20   error message. 
34db0 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72   ^SQLite interpr
34dc0 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a  ets the error.**
34dd0 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
34de0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
34df0 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55  ult_error() as U
34e00 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a  TF-8. ^SQLite.**
34e10 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
34e20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
34e30 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
34e40 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69  16() as UTF-16 i
34e50 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65  n native.** byte
34e60 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65   order.  ^If the
34e70 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
34e80 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
34e90 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
34ea0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34eb0 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67  error16() is neg
34ec0 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
34ed0 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65  e takes as the e
34ee0 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
34ef0 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f  all text up thro
34f00 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
34f10 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
34f20 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
34f30 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
34f40 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
34f50 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
34f60 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
34f70 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  ) is non-negativ
34f80 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
34f90 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a  kes that many.**
34fa0 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
34fb0 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65  acters) from the
34fc0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
34fd0 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  s the error mess
34fe0 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  age..** ^The sql
34ff0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
35000 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
35010 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
35020 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b  .** routines mak
35030 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79  e a private copy
35040 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65   of the error me
35050 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72  ssage text befor
35060 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e  e.** they return
35070 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61  .  Hence, the ca
35080 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  lling function c
35090 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72  an deallocate or
350a0 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74  .** modify the t
350b0 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72  ext after they r
350c0 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61  eturn without ha
350d0 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  rm..** ^The sqli
350e0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
350f0 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e  _code() function
35100 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72   changes the err
35110 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72  or code.** retur
35120 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73  ned by SQLite as
35130 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20   a result of an 
35140 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74  error in a funct
35150 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c  ion.  ^By defaul
35160 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20  t,.** the error 
35170 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45  code is SQLITE_E
35180 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71  RROR.  ^A subseq
35190 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
351a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
351b0 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
351c0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
351d0 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72  () resets the er
351e0 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49  ror code to SQLI
351f0 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20  TE_ERROR..**.** 
35200 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
35210 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67  ult_error_toobig
35220 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
35230 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
35240 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20  row an.** error 
35250 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
35260 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
35270 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20   is too long to 
35280 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a  represent..**.**
35290 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
352a0 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
352b0 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
352c0 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
352d0 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20  row an.** error 
352e0 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
352f0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
35300 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a  ion failed..**.*
35310 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
35320 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65  esult_int() inte
35330 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
35340 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
35350 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
35360 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
35370 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d  on to be the 32-
35380 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
35390 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
353a0 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
353b0 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73  ument..** ^The s
353c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
353d0 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20  t64() interface 
353e0 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
353f0 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
35400 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
35410 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
35420 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69  be the 64-bit si
35430 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
35440 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
35450 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
35460 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
35470 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
35480 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
35490 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
354a0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
354b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
354c0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e  function to be N
354d0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
354e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
354f0 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  ext(), sqlite3_r
35500 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a  esult_text16(),.
35510 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
35520 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e  t_text16le(), an
35530 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
35540 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65  _text16be() inte
35550 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68  rfaces.** set th
35560 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
35570 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
35580 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
35590 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65  on to be.** a te
355a0 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20  xt string which 
355b0 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61  is represented a
355c0 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20  s UTF-8, UTF-16 
355d0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
355e0 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74  r,.** UTF-16 lit
355f0 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55  tle endian, or U
35600 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e  TF-16 big endian
35610 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  , respectively..
35620 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35630 72 65 73 75 6c 74 5f 74 65 78 74 36 34 28 29 20  result_text64() 
35640 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
35650 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
35660 6f 66 20 61 6e 0a 2a 2a 20 61 70 70 6c 69 63 61  of an.** applica
35670 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
35680 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 74 65  ction to be a te
35690 78 74 20 73 74 72 69 6e 67 20 69 6e 20 61 6e 20  xt string in an 
356a0 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 73 70 65 63  encoding.** spec
356b0 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69 66  ified by the fif
356c0 74 68 20 28 61 6e 64 20 6c 61 73 74 29 20 70 61  th (and last) pa
356d0 72 61 6d 65 74 65 72 2c 20 77 68 69 63 68 20 6d  rameter, which m
356e0 75 73 74 20 62 65 20 6f 6e 65 0a 2a 2a 20 6f 66  ust be one.** of
356f0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20   [SQLITE_UTF8], 
35700 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20  [SQLITE_UTF16], 
35710 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
35720 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  , or [SQLITE_UTF
35730 31 36 4c 45 5d 2e 0a 2a 2a 20 5e 53 51 4c 69 74  16LE]..** ^SQLit
35740 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74  e takes the text
35750 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65   result from the
35760 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f   application fro
35770 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72  m.** the 2nd par
35780 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71  ameter of the sq
35790 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
357a0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  t* interfaces..*
357b0 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61  * ^If the 3rd pa
357c0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
357d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
357e0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
357f0 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  * is negative, t
35800 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
35810 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f   result text fro
35820 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
35830 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74  ter.** through t
35840 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
35850 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  aracter..** ^If 
35860 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
35870 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
35880 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
35890 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e  terfaces.** is n
358a0 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
358b0 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20  n as many bytes 
358c0 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
358d0 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20   of the text.** 
358e0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
358f0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
35900 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65  are taken as the
35910 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
35920 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ined.** function
35930 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68 65   result.  If the
35940 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69   3rd parameter i
35950 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
35960 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20  then it.** must 
35970 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73  be the byte offs
35980 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72 69  et into the stri
35990 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c  ng where the NUL
359a0 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c   terminator woul
359b0 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20 74  d.** appear if t
359c0 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20  he string where 
359d0 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  NUL terminated. 
359e0 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72   If any NUL char
359f0 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20  acters occur.** 
35a00 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61 74  in the string at
35a10 20 61 20 62 79 74 65 20 6f 66 66 73 65 74 20 74   a byte offset t
35a20 68 61 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  hat is less than
35a30 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
35a40 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  e 3rd.** paramet
35a50 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  er, then the res
35a60 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77 69  ulting string wi
35a70 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64  ll contain embed
35a80 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68 65  ded NULs and the
35a90 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65 78  .** result of ex
35aa0 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61 74  pressions operat
35ab0 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20 77  ing on strings w
35ac0 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ith embedded NUL
35ad0 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s is undefined..
35ae0 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
35af0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
35b00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
35b10 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
35b20 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
35b30 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e  sult_blob is a n
35b40 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
35b50 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c   then SQLite cal
35b60 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74  ls that.** funct
35b70 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72  ion as the destr
35b80 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78  uctor on the tex
35b90 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74  t or BLOB result
35ba0 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20   when it has.** 
35bb0 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
35bc0 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  hat result..** ^
35bd0 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
35be0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
35bf0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
35c00 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74   interfaces or t
35c10 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  o.** sqlite3_res
35c20 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20  ult_blob is the 
35c30 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74  special constant
35c40 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
35c50 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61  then SQLite.** a
35c60 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20  ssumes that the 
35c70 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
35c80 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61  ult is in consta
35c90 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  nt space and doe
35ca0 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68  s not.** copy th
35cb0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
35cc0 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63   parameter nor c
35cd0 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72  all a destructor
35ce0 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a   on the content.
35cf0 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66  ** when it has f
35d00 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
35d10 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49  at result..** ^I
35d20 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
35d30 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
35d40 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
35d50 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
35d60 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35d70 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
35d80 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
35d90 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a  ITE_TRANSIENT.**
35da0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b   then SQLite mak
35db0 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
35dc0 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61   result into spa
35dd0 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ce obtained from
35de0 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
35df0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f  3_malloc()] befo
35e00 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a  re it returns..*
35e10 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35e20 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
35e30 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
35e40 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a  the result of.**
35e50 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
35e60 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
35e70 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74  n to be a copy t
35e80 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  he.** [unprotect
35e90 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
35ea0 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69  ] object specifi
35eb0 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61  ed by the 2nd pa
35ec0 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a  rameter.  ^The.*
35ed0 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
35ee0 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
35ef0 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  ce makes a copy 
35f00 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
35f10 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61  value].** so tha
35f20 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  t the [sqlite3_v
35f30 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20  alue] specified 
35f40 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
35f50 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a   may change or.*
35f60 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  * be deallocated
35f70 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72   after sqlite3_r
35f80 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65  esult_value() re
35f90 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61  turns without ha
35fa0 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65  rm..** ^A [prote
35fb0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
35fc0 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61  ue] object may a
35fd0 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68  lways be used wh
35fe0 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f  ere an.** [unpro
35ff0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
36000 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20  alue] object is 
36010 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74  required, so eit
36020 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b  her.** kind of [
36030 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
36040 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65  bject can be use
36050 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65  d with this inte
36060 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  rface..**.** If 
36070 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
36080 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77  re called from w
36090 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72  ithin the differ
360a0 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68  ent thread.** th
360b0 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61  an the one conta
360c0 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63  ining the applic
360d0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
360e0 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65  nction that rece
360f0 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  ived.** the [sql
36100 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f  ite3_context] po
36110 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c  inter, the resul
36120 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
36130 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
36140 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71  3_result_blob(sq
36150 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
36160 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
36170 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
36180 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
36190 72 65 73 75 6c 74 5f 62 6c 6f 62 36 34 28 73 71  result_blob64(sq
361a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 63  lite3_context*,c
361b0 6f 6e 73 74 20 76 6f 69 64 2a 2c 73 71 6c 69 74  onst void*,sqlit
361c0 65 33 5f 75 69 6e 74 36 34 2c 76 6f 69 64 28 2a  e3_uint64,void(*
361d0 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
361e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
361f0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  ouble(sqlite3_co
36200 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b  ntext*, double);
36210 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
36220 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74  sult_error(sqlit
36230 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
36240 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a  st char*, int);.
36250 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
36260 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69  ult_error16(sqli
36270 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
36280 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  nst void*, int);
36290 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
362a0 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69  sult_error_toobi
362b0 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  g(sqlite3_contex
362c0 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
362d0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e  3_result_error_n
362e0 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e  omem(sqlite3_con
362f0 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
36300 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
36310 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63  r_code(sqlite3_c
36320 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76  ontext*, int);.v
36330 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
36340 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63  lt_int(sqlite3_c
36350 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76  ontext*, int);.v
36360 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
36370 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  lt_int64(sqlite3
36380 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
36390 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20  e3_int64);.void 
363a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
363b0 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ull(sqlite3_cont
363c0 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
363d0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
363e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
363f0 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
36400 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
36410 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
36420 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 36 34 28  3_result_text64(
36430 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36440 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71  , const char*,sq
36450 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20  lite3_uint64,.  
36460 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36470 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29           void(*)
36480 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65  (void*), unsigne
36490 64 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67 29  d char encoding)
364a0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
364b0 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c  esult_text16(sql
364c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
364d0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
364e0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
364f0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
36500 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73  esult_text16le(s
36510 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
36520 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
36530 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
36540 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
36550 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
36560 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36570 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
36580 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
36590 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
365a0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71  _result_value(sq
365b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
365c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
365d0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
365e0 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  sult_zeroblob(sq
365f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
36600 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
36610 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20  API3REF: Define 
36620 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65  New Collating Se
36630 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54  quences.**.** ^T
36640 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
36650 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d  dd, remove, or m
36660 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69  odify a [collati
36670 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  on] associated.*
36680 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  * with the [data
36690 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
366a0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68   specified as th
366b0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
366c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
366d0 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  e of the collati
366e0 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  on is a UTF-8 st
366f0 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69  ring.** for sqli
36700 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
36710 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  tion() and sqlit
36720 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
36730 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20  ion_v2().** and 
36740 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
36750 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
36760 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33  rder for sqlite3
36770 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
36780 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61  n16()..** ^Colla
36790 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20  tion names that 
367a0 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63  compare equal ac
367b0 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69  cording to [sqli
367c0 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20  te3_strnicmp()] 
367d0 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65  are.** considere
367e0 64 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65  d to be the same
367f0 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   name..**.** ^(T
36800 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
36810 74 20 28 65 54 65 78 74 52 65 70 29 20 6d 75 73  t (eTextRep) mus
36820 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20  t be one of the 
36830 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75  constants:.** <u
36840 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
36850 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69  TE_UTF8],.** <li
36860 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  > [SQLITE_UTF16L
36870 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
36880 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a  ITE_UTF16BE],.**
36890 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
368a0 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  F16], or.** <li>
368b0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
368c0 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LIGNED]..** </ul
368d0 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78  >)^.** ^The eTex
368e0 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65  tRep argument de
368f0 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63  termines the enc
36900 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73  oding of strings
36910 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68   passed.** to th
36920 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
36930 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78  tion callback, x
36940 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68  Callback..** ^Th
36950 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  e [SQLITE_UTF16]
36960 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46   and [SQLITE_UTF
36970 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75  16_ALIGNED] valu
36980 65 73 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a  es for eTextRep.
36990 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73  ** force strings
369a0 20 74 6f 20 62 65 20 55 54 46 31 36 20 77 69 74   to be UTF16 wit
369b0 68 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  h native byte or
369c0 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  der..** ^The [SQ
369d0 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
369e0 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54  ED] value for eT
369f0 65 78 74 52 65 70 20 66 6f 72 63 65 73 20 73 74  extRep forces st
36a00 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a  rings to begin.*
36a10 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74  * on an even byt
36a20 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a  e address..**.**
36a30 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72 67   ^The fourth arg
36a40 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20  ument, pArg, is 
36a50 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  an application d
36a60 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ata pointer that
36a70 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68   is passed.** th
36a80 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
36a90 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
36aa0 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
36ab0 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a  ction callback..
36ac0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
36ad0 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c   argument, xCall
36ae0 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74  back, is a point
36af0 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  er to the collat
36b00 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ing function..**
36b10 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61   ^Multiple colla
36b20 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63  ting functions c
36b30 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64  an be registered
36b40 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
36b50 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68  name but.** with
36b60 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74   different eText
36b70 52 65 70 20 70 61 72 61 6d 65 74 65 72 73 20 61  Rep parameters a
36b80 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  nd SQLite will u
36b90 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20  se whichever.** 
36ba0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
36bb0 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
36bc0 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73  nt of data trans
36bd0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49  formation..** ^I
36be0 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20  f the xCallback 
36bf0 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c  argument is NULL
36c00 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74   then the collat
36c10 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a  ing function is.
36c20 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68  ** deleted.  ^Wh
36c30 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67  en all collating
36c40 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e   functions havin
36c50 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  g the same name 
36c60 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20  are deleted,.** 
36c70 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69  that collation i
36c80 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62  s no longer usab
36c90 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  le..**.** ^The c
36ca0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
36cb0 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  n callback is in
36cc0 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70  voked with a cop
36cd0 79 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a  y of the pArg .*
36ce0 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  * application da
36cf0 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77  ta pointer and w
36d00 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20  ith two strings 
36d10 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  in the encoding 
36d20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
36d30 74 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67  the eTextRep arg
36d40 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c  ument.  The coll
36d50 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
36d60 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a  ust return an.**
36d70 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 69 73   integer that is
36d80 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c   negative, zero,
36d90 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20   or positive.** 
36da0 69 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72  if the first str
36db0 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ing is less than
36dc0 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67  , equal to, or g
36dd0 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20  reater than the 
36de0 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65  second,.** respe
36df0 63 74 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c  ctively.  A coll
36e00 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
36e10 75 73 74 20 61 6c 77 61 79 73 20 72 65 74 75 72  ust always retur
36e20 6e 20 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65  n the same answe
36e30 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73  r.** given the s
36e40 61 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20  ame inputs.  If 
36e50 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c  two or more coll
36e60 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
36e70 61 72 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a  are registered.*
36e80 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f  * to the same co
36e90 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73  llation name (us
36ea0 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20 65 54  ing different eT
36eb0 65 78 74 52 65 70 20 76 61 6c 75 65 73 29 20 74  extRep values) t
36ec0 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20  hen all.** must 
36ed0 67 69 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65  give an equivale
36ee0 6e 74 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69  nt answer when i
36ef0 6e 76 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69  nvoked with equi
36f00 76 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a  valent strings..
36f10 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67  ** The collating
36f20 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f   function must o
36f30 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  bey the followin
36f40 67 20 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72  g properties for
36f50 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20   all.** strings 
36f60 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a  A, B, and C:.**.
36f70 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ol>.** <li> 
36f80 49 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d  If A==B then B==
36f90 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d  A..** <li> If A=
36fa0 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e  =B and B==C then
36fb0 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49   A==C..** <li> I
36fc0 66 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26  f A&lt;B THEN B&
36fd0 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66  gt;A..** <li> If
36fe0 20 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74   A&lt;B and B&lt
36ff0 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a  ;C then A&lt;C..
37000 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ol>.**.** I
37010 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  f a collating fu
37020 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79  nction fails any
37030 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f   of the above co
37040 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68  nstraints and th
37050 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20  at.** collating 
37060 66 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67  function is  reg
37070 69 73 74 65 72 65 64 20 61 6e 64 20 75 73 65 64  istered and used
37080 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
37090 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ior of SQLite.**
370a0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
370b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
370c0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
370d0 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69  on_v2() works li
370e0 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ke sqlite3_creat
370f0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a  e_collation().**
37100 20 77 69 74 68 20 74 68 65 20 61 64 64 69 74 69   with the additi
37110 6f 6e 20 74 68 61 74 20 74 68 65 20 78 44 65 73  on that the xDes
37120 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  troy callback is
37130 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67   invoked on pArg
37140 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c   when.** the col
37150 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
37160 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e  is deleted..** ^
37170 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  Collating functi
37180 6f 6e 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ons are deleted 
37190 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76  when they are ov
371a0 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65  erridden by late
371b0 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68  r.** calls to th
371c0 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61  e collation crea
371d0 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f  tion functions o
371e0 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64  r when the.** [d
371f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37200 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73  on] is closed us
37210 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  ing [sqlite3_clo
37220 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  se()]..**.** ^Th
37230 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62  e xDestroy callb
37240 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75  ack is <u>not</u
37250 3e 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20  > called if the 
37260 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
37270 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
37280 29 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73  ) function fails
37290 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
372a0 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  that invoke.** s
372b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
372c0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74  llation_v2() wit
372d0 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65  h a non-NULL xDe
372e0 73 74 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73  stroy argument s
372f0 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20  hould .** check 
37300 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
37310 61 6e 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74  and dispose of t
37320 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
37330 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ata pointer.** t
37340 68 65 6d 73 65 6c 76 65 73 20 72 61 74 68 65 72  hemselves rather
37350 20 74 68 61 6e 20 65 78 70 65 63 74 69 6e 67 20   than expecting 
37360 53 51 4c 69 74 65 20 74 6f 20 64 65 61 6c 20 77  SQLite to deal w
37370 69 74 68 20 69 74 20 66 6f 72 20 74 68 65 6d 2e  ith it for them.
37380 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 69 66 66  .** This is diff
37390 65 72 65 6e 74 20 66 72 6f 6d 20 65 76 65 72 79  erent from every
373a0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
373b0 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 69 6e  terface.  The in
373c0 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20  consistency .** 
373d0 69 73 20 75 6e 66 6f 72 74 75 6e 61 74 65 20 62  is unfortunate b
373e0 75 74 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61  ut cannot be cha
373f0 6e 67 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  nged without bre
37400 61 6b 69 6e 67 20 62 61 63 6b 77 61 72 64 73 20  aking backwards 
37410 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
37420 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  y..**.** See als
37430 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  o:  [sqlite3_col
37440 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d  lation_needed()]
37450 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f   and [sqlite3_co
37460 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
37470 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
37480 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
37490 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a  tion(.  sqlite3*
374a0 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
374b0 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
374c0 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
374d0 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78   *pArg,.  int(*x
374e0 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
374f0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
37500 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
37510 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
37520 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
37530 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  v2(.  sqlite3*, 
37540 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
37550 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
37560 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a  xtRep, .  void *
37570 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  pArg,.  int(*xCo
37580 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
37590 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
375a0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20  ,const void*),. 
375b0 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
375c0 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73  (void*).);.int s
375d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
375e0 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  llation16(.  sql
375f0 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
37600 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69  void *zName,.  i
37610 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
37620 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e  void *pArg,.  in
37630 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
37640 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
37650 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
37660 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*).);../*.** CA
37670 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f  PI3REF: Collatio
37680 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63  n Needed Callbac
37690 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f  ks.**.** ^To avo
376a0 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67  id having to reg
376b0 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74  ister all collat
376c0 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65  ion sequences be
376d0 66 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a  fore a database.
376e0 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20  ** can be used, 
376f0 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63  a single callbac
37700 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  k function may b
37710 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74  e registered wit
37720 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  h the.** [databa
37730 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
37740 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
37750 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e  never an undefin
37760 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20  ed collation.** 
37770 73 65 71 75 65 6e 63 65 20 69 73 20 72 65 71 75  sequence is requ
37780 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ired..**.** ^If 
37790 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
377a0 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
377b0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
377c0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
377d0 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20  API,.** then it 
377e0 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61  is passed the na
377f0 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64  mes of undefined
37800 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
37810 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a  nces as strings.
37820 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54  ** encoded in UT
37830 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33  F-8. ^If sqlite3
37840 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
37850 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a  d16() is used,.*
37860 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20  * the names are 
37870 70 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36  passed as UTF-16
37880 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69   in machine nati
37890 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
378a0 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74  * ^A call to eit
378b0 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70  her function rep
378c0 6c 61 63 65 73 20 74 68 65 20 65 78 69 73 74 69  laces the existi
378d0 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65  ng collation-nee
378e0 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ded callback..**
378f0 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63  .** ^(When the c
37900 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
37910 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72  ed, the first ar
37920 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73  gument passed is
37930 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68   a copy.** of th
37940 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
37950 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  t to sqlite3_col
37960 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
37970 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
37980 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
37990 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ().  The second 
379a0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
379b0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
379c0 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69  ection.  The thi
379d0 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  rd argument is o
379e0 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54  ne of [SQLITE_UT
379f0 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  F8], [SQLITE_UTF
37a00 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51  16BE],.** or [SQ
37a10 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69  LITE_UTF16LE], i
37a20 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f  ndicating the mo
37a30 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72  st desirable for
37a40 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  m of the collati
37a50 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66  on.** sequence f
37a60 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64  unction required
37a70 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
37a80 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
37a90 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  ame of the.** re
37aa0 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  quired collation
37ab0 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a   sequence.)^.**.
37ac0 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
37ad0 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
37ae0 72 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73  register the des
37af0 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75  ired collation u
37b00 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
37b10 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
37b20 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  n()], [sqlite3_c
37b30 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
37b40 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
37b50 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
37b60 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a  ation_v2()]..*/.
37b70 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  int sqlite3_coll
37b80 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20  ation_needed(.  
37b90 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
37ba0 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76  d*, .  void(*)(v
37bb0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
37bc0 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
37bd0 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73   char*).);.int s
37be0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
37bf0 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c  _needed16(.  sql
37c00 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
37c10 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
37c20 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
37c30 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69  extRep,const voi
37c40 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53  d*).);..#ifdef S
37c50 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a  QLITE_HAS_CODEC.
37c60 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68  /*.** Specify th
37c70 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63  e key for an enc
37c80 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e  rypted database.
37c90 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73    This routine s
37ca0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c  hould be.** call
37cb0 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73  ed right after s
37cc0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a  qlite3_open()..*
37cd0 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f  *.** The code to
37ce0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20   implement this 
37cf0 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c  API is not avail
37d00 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c  able in the publ
37d10 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66  ic release.** of
37d20 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20   SQLite..*/.int 
37d30 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73  sqlite3_key(.  s
37d40 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
37d50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
37d60 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   Database to be 
37d70 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e  rekeyed */.  con
37d80 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
37d90 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
37da0 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 69 6e 74  he key */.);.int
37db0 20 73 71 6c 69 74 65 33 5f 6b 65 79 5f 76 32 28   sqlite3_key_v2(
37dc0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
37dd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37de0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
37df0 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
37e00 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
37e10 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 20 20  Name,           
37e20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64  /* Name of the d
37e30 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
37e40 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
37e50 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
37e60 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a  he key */.);../*
37e70 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b  .** Change the k
37e80 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61  ey on an open da
37e90 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20  tabase.  If the 
37ea0 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65  current database
37eb0 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79   is not.** encry
37ec0 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69  pted, this routi
37ed0 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20  ne will encrypt 
37ee0 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20  it.  If pNew==0 
37ef0 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a  or nNew==0, the.
37f00 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64  ** database is d
37f10 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ecrypted..**.** 
37f20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
37f30 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
37f40 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
37f50 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
37f60 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
37f70 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
37f80 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69  e3_rekey(.  sqli
37f90 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
37fa0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
37fb0 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b  tabase to be rek
37fc0 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  eyed */.  const 
37fd0 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20  void *pKey, int 
37fe0 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20  nKey     /* The 
37ff0 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 69 6e  new key */.);.in
38000 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 5f  t sqlite3_rekey_
38010 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
38020 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
38030 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
38040 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a   to be rekeyed *
38050 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
38060 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20  zDbName,        
38070 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
38080 65 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  e database */.  
38090 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79  const void *pKey
380a0 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f  , int nKey     /
380b0 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f  * The new key */
380c0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  .);../*.** Speci
380d0 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f  fy the activatio
380e0 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45 45 20  n key for a SEE 
380f0 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73  database.  Unles
38100 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c  s .** activated,
38110 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 45 45   none of the SEE
38120 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77   routines will w
38130 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ork..*/.void sql
38140 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 73 65  ite3_activate_se
38150 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  e(.  const char 
38160 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20  *zPassPhrase    
38170 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f      /* Activatio
38180 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23  n phrase */.);.#
38190 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 53 51  endif..#ifdef SQ
381a0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f  LITE_ENABLE_CERO
381b0 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  D./*.** Specify 
381c0 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b  the activation k
381d0 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44 20 64  ey for a CEROD d
381e0 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73  atabase.  Unless
381f0 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20   .** activated, 
38200 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45 52 4f  none of the CERO
38210 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20  D routines will 
38220 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  work..*/.void sq
38230 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 63  lite3_activate_c
38240 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63 68  erod(.  const ch
38250 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20  ar *zPassPhrase 
38260 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61         /* Activa
38270 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29  tion phrase */.)
38280 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ;.#endif../*.** 
38290 43 41 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e  CAPI3REF: Suspen
382a0 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20  d Execution For 
382b0 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a  A Short Time.**.
382c0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  ** The sqlite3_s
382d0 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20  leep() function 
382e0 63 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65  causes the curre
382f0 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73  nt thread to sus
38300 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a  pend execution.*
38310 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61  * for at least a
38320 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69   number of milli
38330 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65  seconds specifie
38340 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74  d in its paramet
38350 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  er..**.** If the
38360 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
38370 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f  m does not suppo
38380 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74  rt sleep request
38390 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73  s with.** millis
383a0 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c  econd time resol
383b0 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ution, then the 
383c0 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75  time will be rou
383d0 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68  nded up to.** th
383e0 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64  e nearest second
383f0 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  . The number of 
38400 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
38410 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a  sleep actually.*
38420 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d  * requested from
38430 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
38440 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65  ystem is returne
38450 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  d..**.** ^SQLite
38460 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73   implements this
38470 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 63 61   interface by ca
38480 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70  lling the xSleep
38490 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20  ().** method of 
384a0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
384b0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
384c0 2e 20 20 49 66 20 74 68 65 20 78 53 6c 65 65 70  .  If the xSleep
384d0 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20  () method.** of 
384e0 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
384f0 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74  is not implement
38500 65 64 20 63 6f 72 72 65 63 74 6c 79 2c 20 6f 72  ed correctly, or
38510 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64   not implemented
38520 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e   at.** all, then
38530 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
38540 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29   sqlite3_sleep()
38550 20 6d 61 79 20 64 65 76 69 61 74 65 20 66 72 6f   may deviate fro
38560 6d 20 74 68 65 20 64 65 73 63 72 69 70 74 69 6f  m the descriptio
38570 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72 65 76  n.** in the prev
38580 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 73 2e  ious paragraphs.
38590 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
385a0 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  sleep(int);../*.
385b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
385c0 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20  e Of The Folder 
385d0 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72  Holding Temporar
385e0 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28  y Files.**.** ^(
385f0 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76  If this global v
38600 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20  ariable is made 
38610 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  to point to a st
38620 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a  ring which is.**
38630 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66   the name of a f
38640 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69  older (a.k.a. di
38650 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61  rectory), then a
38660 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ll temporary fil
38670 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  es.** created by
38680 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69   SQLite when usi
38690 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73  ng a built-in [s
386a0 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53  qlite3_vfs | VFS
386b0 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61  ].** will be pla
386c0 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65  ced in that dire
386d0 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74 68  ctory.)^  ^If th
386e0 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69  is variable.** i
386f0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
38700 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65  , then SQLite pe
38710 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20  rforms a search 
38720 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61  for an appropria
38730 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
38740 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a  file directory..
38750 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
38760 6e 73 20 61 72 65 20 73 74 72 6f 6e 67 6c 79 20  ns are strongly 
38770 64 69 73 63 6f 75 72 61 67 65 64 20 66 72 6f 6d  discouraged from
38780 20 75 73 69 6e 67 20 74 68 69 73 20 67 6c 6f 62   using this glob
38790 61 6c 20 76 61 72 69 61 62 6c 65 2e 0a 2a 2a 20  al variable..** 
387a0 49 74 20 69 73 20 72 65 71 75 69 72 65 64 20 74  It is required t
387b0 6f 20 73 65 74 20 61 20 74 65 6d 70 6f 72 61 72  o set a temporar
387c0 79 20 66 6f 6c 64 65 72 20 6f 6e 20 57 69 6e 64  y folder on Wind
387d0 6f 77 73 20 52 75 6e 74 69 6d 65 20 28 57 69 6e  ows Runtime (Win
387e0 52 54 29 2e 0a 2a 2a 20 42 75 74 20 66 6f 72 20  RT)..** But for 
387f0 61 6c 6c 20 6f 74 68 65 72 20 70 6c 61 74 66 6f  all other platfo
38800 72 6d 73 2c 20 69 74 20 69 73 20 68 69 67 68 6c  rms, it is highl
38810 79 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  y recommended th
38820 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  at applications.
38830 2a 2a 20 6e 65 69 74 68 65 72 20 72 65 61 64 20  ** neither read 
38840 6e 6f 72 20 77 72 69 7