/ Hex Artifact Content
Login

Artifact 66a923e0d8a3a771a7050f292cc8028b8c711652:


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 20  atements.** and 
2c60: 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74  unfinished sqlit
2c70: 65 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e  e3_backups, then
2c80: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2c90: 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73  nnection becomes
2ca0: 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20  .** an unusable 
2cb0: 22 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77  "zombie" which w
2cc0: 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ill automaticall
2cd0: 79 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  y be deallocated
2ce0: 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73   when the.** las
2cf0: 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
2d00: 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65  ment is finalize
2d10: 64 20 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71  d or the last sq
2d20: 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a  lite3_backup is.
2d30: 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68  ** finished.  Th
2d40: 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  e sqlite3_close_
2d50: 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  v2() interface i
2d60: 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  s intended for u
2d70: 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20  se with.** host 
2d80: 6c 61 6e 67 75 61 67 65 73 20 74 68 61 74 20 61  languages that a
2d90: 72 65 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65  re garbage colle
2da0: 63 74 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20  cted, and where 
2db0: 74 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69  the order in whi
2dc0: 63 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72  ch.** destructor
2dd0: 73 20 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20  s are called is 
2de0: 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a  arbitrary..**.**
2df0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
2e00: 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ould [sqlite3_fi
2e10: 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a  nalize | finaliz
2e20: 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64  e] all [prepared
2e30: 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a   statements],.**
2e40: 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63   [sqlite3_blob_c
2e50: 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c  lose | close] al
2e60: 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d  l [BLOB handles]
2e70: 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74  , and .** [sqlit
2e80: 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68  e3_backup_finish
2e90: 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b   | finish] all [
2ea0: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20  sqlite3_backup] 
2eb0: 6f 62 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74  objects associat
2ec0: 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  ed.** with the [
2ed0: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2ee0: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
2ef0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
2f00: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
2f10: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
2f20: 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e  2() is called on
2f30: 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
2f40: 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74  nection] that st
2f50: 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74  ill has.** outst
2f60: 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64  anding [prepared
2f70: 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42   statements], [B
2f80: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e  LOB handles], an
2f90: 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d/or.** [sqlite3
2fa0: 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73  _backup] objects
2fb0: 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73   then it returns
2fc0: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 62 75 74   [SQLITE_OK] but
2fd0: 20 74 68 65 20 64 65 61 6c 6c 6f 63 61 74 69 6f   the deallocatio
2fe0: 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72 63 65  n.** of resource
2ff0: 73 20 69 73 20 64 65 66 65 72 72 65 64 20 75 6e  s is deferred un
3000: 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61 72 65  til all [prepare
3010: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b  d statements], [
3020: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a  BLOB handles],.*
3030: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  * and [sqlite3_b
3040: 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61  ackup] objects a
3050: 72 65 20 61 6c 73 6f 20 64 65 73 74 72 6f 79 65  re also destroye
3060: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  d..**.** ^If an 
3070: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
3080: 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 77 68   is destroyed wh
3090: 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ile a transactio
30a0: 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68  n is open,.** th
30b0: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  e transaction is
30c0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
30d0: 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a  olled back..**.*
30e0: 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65 74 65  * The C paramete
30f0: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  r to [sqlite3_cl
3100: 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b 73 71 6c  ose(C)] and [sql
3110: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 43 29  ite3_close_v2(C)
3120: 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74  ].** must be eit
3130: 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f  her a NULL.** po
3140: 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c  inter or an [sql
3150: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69  ite3] object poi
3160: 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  nter obtained.**
3170: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f   from [sqlite3_o
3180: 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
3190: 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a  _open16()], or.*
31a0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  * [sqlite3_open_
31b0: 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70  v2()], and not p
31c0: 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64  reviously closed
31d0: 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71  ..** ^Calling sq
31e0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 6f 72  lite3_close() or
31f0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
3200: 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  2() with a NULL 
3210: 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67 75 6d  pointer.** argum
3220: 65 6e 74 20 69 73 20 61 20 68 61 72 6d 6c 65 73  ent is a harmles
3230: 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20  s no-op..*/.int 
3240: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71  sqlite3_close(sq
3250: 6c 69 74 65 33 2a 29 3b 0a 69 6e 74 20 73 71 6c  lite3*);.int sql
3260: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73 71  ite3_close_v2(sq
3270: 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
3280: 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 63  The type for a c
3290: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
32a0: 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67  ..** This is leg
32b0: 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 74  acy and deprecat
32c0: 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75  ed.  It is inclu
32d0: 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ded for historic
32e0: 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  al.** compatibil
32f0: 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64  ity and is not d
3300: 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79  ocumented..*/.ty
3310: 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69  pedef int (*sqli
3320: 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f  te3_callback)(vo
3330: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20  id*,int,char**, 
3340: 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  char**);../*.** 
3350: 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74  CAPI3REF: One-St
3360: 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74 69  ep Query Executi
3370: 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a  on Interface.**.
3380: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
3390: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
33a0: 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65  is a convenience
33b0: 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
33c0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
33d0: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
33e0: 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64  te3_step()], and
33f0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
3400: 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61  ze()],.** that a
3410: 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61  llows an applica
3420: 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74  tion to run mult
3430: 69 70 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20  iple statements 
3440: 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75  of SQL.** withou
3450: 74 20 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20  t having to use 
3460: 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e  a lot of C code.
3470: 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c   .**.** ^The sql
3480: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
3490: 72 66 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20  rface runs zero 
34a0: 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e  or more UTF-8 en
34b0: 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f  coded,.** semico
34c0: 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c  lon-separate SQL
34d0: 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73   statements pass
34e0: 65 64 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20  ed into its 2nd 
34f0: 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20  argument,.** in 
3500: 74 68 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74  the context of t
3510: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
3520: 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20  nection] passed 
3530: 69 6e 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a  in as its 1st.**
3540: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20   argument.  ^If 
3550: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  the callback fun
3560: 63 74 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64  ction of the 3rd
3570: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
3580: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3590: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
35a0: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66   it is invoked f
35b0: 6f 72 20 65 61 63 68 20 72 65 73 75 6c 74 20 72  or each result r
35c0: 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74  ow.** coming out
35d0: 20 6f 66 20 74 68 65 20 65 76 61 6c 75 61 74 65   of the evaluate
35e0: 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  d SQL statements
35f0: 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75  .  ^The 4th argu
3600: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  ment to.** sqlit
3610: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c  e3_exec() is rel
3620: 61 79 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20  ayed through to 
3630: 74 68 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74  the 1st argument
3640: 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c   of each.** call
3650: 62 61 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e  back invocation.
3660: 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61    ^If the callba
3670: 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71  ck pointer to sq
3680: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
3690: 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f  is NULL, then no
36a0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65   callback is eve
36b0: 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65  r invoked and re
36c0: 73 75 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a  sult rows are.**
36d0: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
36e0: 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  ^If an error occ
36f0: 75 72 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61  urs while evalua
3700: 74 69 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61  ting the SQL sta
3710: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69  tements passed i
3720: 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  nto.** sqlite3_e
3730: 78 65 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63  xec(), then exec
3740: 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72  ution of the cur
3750: 72 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73  rent statement s
3760: 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73  tops and.** subs
3770: 65 71 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74  equent statement
3780: 73 20 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20  s are skipped.  
3790: 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61  ^If the 5th para
37a0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
37b0: 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f  _exec().** is no
37c0: 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20  t NULL then any 
37d0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73  error message is
37e0: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
37f0: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  mory obtained.**
3800: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
3810: 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73  alloc()] and pas
3820: 73 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68  sed back through
3830: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
3840: 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20  er..** To avoid 
3850: 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68  memory leaks, th
3860: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
3870: 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  ould invoke [sql
3880: 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20  ite3_free()].** 
3890: 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  on error message
38a0: 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
38b0: 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  d through the 5t
38c0: 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a  h parameter of.*
38d0: 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65  * of sqlite3_exe
38e0: 63 28 29 20 61 66 74 65 72 20 74 68 65 20 65 72  c() after the er
38f0: 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
3900: 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ng is no longer 
3910: 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74  needed..** ^If t
3920: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
3930: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
3940: 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61  () is not NULL a
3950: 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20  nd no errors.** 
3960: 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69  occur, then sqli
3970: 74 65 33 5f 65 78 65 63 28 29 20 73 65 74 73 20  te3_exec() sets 
3980: 74 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69  the pointer in i
3990: 74 73 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  ts 5th parameter
39a0: 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f   to.** NULL befo
39b0: 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a  re returning..**
39c0: 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74  .** ^If an sqlit
39d0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
39e0: 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
39f0: 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ero, the sqlite3
3a00: 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69  _exec().** routi
3a10: 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  ne returns SQLIT
3a20: 45 5f 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20  E_ABORT without 
3a30: 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c  invoking the cal
3a40: 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a  lback again and.
3a50: 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69  ** without runni
3a60: 6e 67 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  ng any subsequen
3a70: 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  t SQL statements
3a80: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64  ..**.** ^The 2nd
3a90: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3aa0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3ab0: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
3ac0: 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  n is the.** numb
3ad0: 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
3ae0: 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54   the result.  ^T
3af0: 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20  he 3rd argument 
3b00: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  to the sqlite3_e
3b10: 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63  xec().** callbac
3b20: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  k is an array of
3b30: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
3b40: 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73  ings obtained as
3b50: 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c   if from.** [sql
3b60: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
3b70: 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63  ()], one for eac
3b80: 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61  h column.  ^If a
3b90: 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a  n element of a.*
3ba0: 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20  * result row is 
3bb0: 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f  NULL then the co
3bc0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69  rresponding stri
3bd0: 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  ng pointer for t
3be0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
3bf0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
3c00: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
3c10: 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d    ^The 4th argum
3c20: 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71  ent to the.** sq
3c30: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
3c40: 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61  lback is an arra
3c50: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
3c60: 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20 65   strings where e
3c70: 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70  ach.** entry rep
3c80: 72 65 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65  resents the name
3c90: 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e   of correspondin
3ca0: 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  g result column 
3cb0: 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  as obtained.** f
3cc0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  rom [sqlite3_col
3cd0: 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a  umn_name()]..**.
3ce0: 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70  ** ^If the 2nd p
3cf0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3d00: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 61 20  te3_exec() is a 
3d10: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20  NULL pointer, a 
3d20: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e  pointer.** to an
3d30: 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f   empty string, o
3d40: 72 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74  r a pointer that
3d50: 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77   contains only w
3d60: 68 69 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72  hitespace and/or
3d70: 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74   .** SQL comment
3d80: 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73  s, then no SQL s
3d90: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76  tatements are ev
3da0: 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65 20  aluated and the 
3db0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e  database.** is n
3dc0: 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a  ot changed..**.*
3dd0: 2a 20 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a  * Restrictions:.
3de0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
3df0: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
3e00: 6f 6e 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74  on must insure t
3e10: 68 61 74 20 74 68 65 20 31 73 74 20 70 61 72 61  hat the 1st para
3e20: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
3e30: 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20  _exec().**      
3e40: 69 73 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f  is a valid and o
3e50: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
3e60: 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c  nnection]..** <l
3e70: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
3e80: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73  on must not clos
3e90: 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  e the [database 
3ea0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
3eb0: 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  ified by.**     
3ec0: 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74   the 1st paramet
3ed0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3ee0: 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74  ec() while sqlit
3ef0: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e  e3_exec() is run
3f00: 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  ning..** <li> Th
3f10: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
3f20: 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68  st not modify th
3f30: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
3f40: 74 65 78 74 20 70 61 73 73 65 64 20 69 6e 74 6f  text passed into
3f50: 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e 64  .**      the 2nd
3f60: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71   parameter of sq
3f70: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69  lite3_exec() whi
3f80: 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  le sqlite3_exec(
3f90: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  ) is running..**
3fa0: 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71   </ul>.*/.int sq
3fb0: 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71  lite3_exec(.  sq
3fc0: 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20  lite3*,         
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 2f 2a 20 41 6e 20 6f           /* An o
3ff0: 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  pen database */.
4000: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71    const char *sq
4010: 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  l,              
4020: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
4030: 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
4040: 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63  ted */.  int (*c
4050: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69  allback)(void*,i
4060: 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a  nt,char**,char**
4070: 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  ),  /* Callback 
4080: 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
4090: 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20  id *,           
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 2f 2a 20 31 73 74 20           /* 1st 
40c0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c  argument to call
40d0: 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a  back */.  char *
40e0: 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20  *errmsg         
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4100: 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73       /* Error ms
4110: 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  g written here *
4120: 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
4130: 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64  3REF: Result Cod
4140: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
4150: 7b 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66  {result code def
4160: 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  initions}.**.** 
4170: 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63  Many SQLite func
4180: 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20  tions return an 
4190: 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63  integer result c
41a0: 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74  ode from the set
41b0: 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69   shown.** here i
41c0: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63  n order to indic
41d0: 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20 66  ate success or f
41e0: 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  ailure..**.** Ne
41f0: 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61  w error codes ma
4200: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
4210: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
4220: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53   SQLite..**.** S
4230: 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74 65 6e 64  ee also: [extend
4240: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 64  ed result code d
4250: 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a 2f 0a 23  efinitions].*/.#
4260: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b  define SQLITE_OK
4270: 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
4280: 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73  * Successful res
4290: 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e  ult */./* beginn
42a0: 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  ing-of-error-cod
42b0: 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  es */.#define SQ
42c0: 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20  LITE_ERROR      
42d0: 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72    1   /* SQL err
42e0: 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61  or or missing da
42f0: 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e  tabase */.#defin
4300: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41  e SQLITE_INTERNA
4310: 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74  L     2   /* Int
4320: 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f  ernal logic erro
4330: 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23  r in SQLite */.#
4340: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45  define SQLITE_PE
4350: 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f  RM         3   /
4360: 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73  * Access permiss
4370: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64  ion denied */.#d
4380: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f  efine SQLITE_ABO
4390: 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a  RT        4   /*
43a0: 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   Callback routin
43b0: 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61  e requested an a
43c0: 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  bort */.#define 
43d0: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20  SQLITE_BUSY     
43e0: 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64      5   /* The d
43f0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
4400: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e  locked */.#defin
4410: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20  e SQLITE_LOCKED 
4420: 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74        6   /* A t
4430: 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61  able in the data
4440: 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a  base is locked *
4450: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4460: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20  _NOMEM        7 
4470: 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20    /* A malloc() 
4480: 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e  failed */.#defin
4490: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
44a0: 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74  Y     8   /* Att
44b0: 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20  empt to write a 
44c0: 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73  readonly databas
44d0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
44e0: 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20  ITE_INTERRUPT   
44f0: 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f   9   /* Operatio
4500: 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20  n terminated by 
4510: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
4520: 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t()*/.#define SQ
4530: 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20  LITE_IOERR      
4540: 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69   10   /* Some ki
4550: 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65  nd of disk I/O e
4560: 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f  rror occurred */
4570: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4580: 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20  CORRUPT     11  
4590: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
45a0: 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d   disk image is m
45b0: 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66  alformed */.#def
45c0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  ine SQLITE_NOTFO
45d0: 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 55  UND    12   /* U
45e0: 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e  nknown opcode in
45f0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f   sqlite3_file_co
4600: 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69  ntrol() */.#defi
4610: 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20  ne SQLITE_FULL  
4620: 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e        13   /* In
4630: 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62  sertion failed b
4640: 65 63 61 75 73 65 20 64 61 74 61 62 61 73 65 20  ecause database 
4650: 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69  is full */.#defi
4660: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
4670: 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e  EN    14   /* Un
4680: 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65  able to open the
4690: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a   database file *
46a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
46b0: 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20  _PROTOCOL    15 
46c0: 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f    /* Database lo
46d0: 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f  ck protocol erro
46e0: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
46f0: 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20  ITE_EMPTY       
4700: 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  16   /* Database
4710: 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65   is empty */.#de
4720: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45  fine SQLITE_SCHE
4730: 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20  MA      17   /* 
4740: 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  The database sch
4750: 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23  ema changed */.#
4760: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f  define SQLITE_TO
4770: 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20 2f  OBIG      18   /
4780: 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  * String or BLOB
4790: 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69   exceeds size li
47a0: 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  mit */.#define S
47b0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
47c0: 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20    19   /* Abort 
47d0: 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e  due to constrain
47e0: 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23  t violation */.#
47f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49  define SQLITE_MI
4800: 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 2f  SMATCH    20   /
4810: 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d  * Data type mism
4820: 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20  atch */.#define 
4830: 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20  SQLITE_MISUSE   
4840: 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61     21   /* Libra
4850: 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63  ry used incorrec
4860: 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  tly */.#define S
4870: 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20  QLITE_NOLFS     
4880: 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f    22   /* Uses O
4890: 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73  S features not s
48a0: 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74  upported on host
48b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
48c0: 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 32  TE_AUTH        2
48d0: 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61  3   /* Authoriza
48e0: 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23  tion denied */.#
48f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f  define SQLITE_FO
4900: 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 2f  RMAT      24   /
4910: 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 61  * Auxiliary data
4920: 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f  base format erro
4930: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
4940: 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20  ITE_RANGE       
4950: 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61  25   /* 2nd para
4960: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
4970: 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e  _bind out of ran
4980: 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ge */.#define SQ
4990: 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20  LITE_NOTADB     
49a0: 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70   26   /* File op
49b0: 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74  ened that is not
49c0: 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
49d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
49e0: 54 45 5f 4e 4f 54 49 43 45 20 20 20 20 20 20 32  TE_NOTICE      2
49f0: 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69 63 61 74  7   /* Notificat
4a00: 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c 69 74 65  ions from sqlite
4a10: 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69  3_log() */.#defi
4a20: 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e  ne SQLITE_WARNIN
4a30: 47 20 20 20 20 20 32 38 20 20 20 2f 2a 20 57 61  G     28   /* Wa
4a40: 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73 71 6c 69  rnings from sqli
4a50: 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65  te3_log() */.#de
4a60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20  fine SQLITE_ROW 
4a70: 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20          100  /* 
4a80: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
4a90: 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72  as another row r
4aa0: 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  eady */.#define 
4ab0: 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20  SQLITE_DONE     
4ac0: 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74     101  /* sqlit
4ad0: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69  e3_step() has fi
4ae0: 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
4af0: 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72   */./* end-of-er
4b00: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a  ror-codes */../*
4b10: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78  .** CAPI3REF: Ex
4b20: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
4b30: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
4b40: 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   {extended resul
4b50: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
4b60: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73  ns}.**.** In its
4b70: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
4b80: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41  ration, SQLite A
4b90: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  PI routines retu
4ba0: 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20 69 6e 74  rn one of 30 int
4bb0: 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75 6c 74 20  eger.** [result 
4bc0: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72  codes].  However
4bd0: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73  , experience has
4be0: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79   shown that many
4bf0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73   of.** these res
4c00: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f  ult codes are to
4c10: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64  o coarse-grained
4c20: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70  .  They do not p
4c30: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63  rovide as.** muc
4c40: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  h information ab
4c50: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20  out problems as 
4c60: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
4c70: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65  t like.  In an e
4c80: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72  ffort to.** addr
4c90: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20  ess this, newer 
4ca0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
4cb0: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e  te (version 3.3.
4cc0: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63  8 and later) inc
4cd0: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20  lude.** support 
4ce0: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72  for additional r
4cf0: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74  esult codes that
4d00: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65   provide more de
4d10: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69  tailed informati
4d20: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f  on.** about erro
4d30: 72 73 2e 20 54 68 65 73 65 20 5b 65 78 74 65 6e  rs. These [exten
4d40: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4d50: 5d 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72  ] are enabled or
4d60: 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20   disabled.** on 
4d70: 61 20 70 65 72 20 64 61 74 61 62 61 73 65 20 63  a per database c
4d80: 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20  onnection basis 
4d90: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
4da0: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
4db0: 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41  esult_codes()] A
4dc0: 50 49 2e 20 20 4f 72 2c 20 74 68 65 20 65 78 74  PI.  Or, the ext
4dd0: 65 6e 64 65 64 20 63 6f 64 65 20 66 6f 72 0a 2a  ended code for.*
4de0: 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  * the most recen
4df0: 74 20 65 72 72 6f 72 20 63 61 6e 20 62 65 20 6f  t error can be o
4e00: 62 74 61 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a  btained using.**
4e10: 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64   [sqlite3_extend
4e20: 65 64 5f 65 72 72 63 6f 64 65 28 29 5d 2e 0a 2a  ed_errcode()]..*
4e30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4e40: 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20  _IOERR_READ     
4e50: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4e60: 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29  _IOERR | (1<<8))
4e70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4e80: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
4e90: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4ea0: 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a  IOERR | (2<<8)).
4eb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4ec0: 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20  OERR_WRITE      
4ed0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4ee0: 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23  OERR | (3<<8)).#
4ef0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4f00: 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20  ERR_FSYNC       
4f10: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4f20: 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  ERR | (4<<8)).#d
4f30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4f40: 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20  RR_DIR_FSYNC    
4f50: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4f60: 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  RR | (5<<8)).#de
4f70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4f80: 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20  R_TRUNCATE      
4f90: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4fa0: 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66  R | (6<<8)).#def
4fb0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4fc0: 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20  _FSTAT          
4fd0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4fe0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
4ff0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5000: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  UNLOCK          
5010: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5020: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (8<<8)).#defin
5030: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
5040: 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  DLOCK           
5050: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5060: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
5070: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45   SQLITE_IOERR_DE
5080: 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
5090: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
50a0: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (10<<8)).#define
50b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c   SQLITE_IOERR_BL
50c0: 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20  OCKED           
50d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
50e0: 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (11<<8)).#define
50f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f   SQLITE_IOERR_NO
5100: 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20  MEM             
5110: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5120: 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (12<<8)).#define
5130: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43   SQLITE_IOERR_AC
5140: 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20  CESS            
5150: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5160: 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (13<<8)).#define
5170: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48   SQLITE_IOERR_CH
5180: 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20  ECKRESERVEDLOCK 
5190: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
51a0: 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (14<<8)).#define
51b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f   SQLITE_IOERR_LO
51c0: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CK              
51d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
51e0: 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (15<<8)).#define
51f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c   SQLITE_IOERR_CL
5200: 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20  OSE             
5210: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5220: 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (16<<8)).#define
5230: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
5240: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
5250: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5260: 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (17<<8)).#define
5270: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
5280: 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20  MOPEN           
5290: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
52a0: 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (18<<8)).#define
52b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
52c0: 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  MSIZE           
52d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
52e0: 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (19<<8)).#define
52f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
5300: 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  MLOCK           
5310: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5320: 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (20<<8)).#define
5330: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
5340: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20  MMAP            
5350: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5360: 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (21<<8)).#define
5370: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45   SQLITE_IOERR_SE
5380: 45 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EK              
5390: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
53a0: 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (22<<8)).#define
53b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45   SQLITE_IOERR_DE
53c0: 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20  LETE_NOENT      
53d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
53e0: 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (23<<8)).#define
53f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d   SQLITE_IOERR_MM
5400: 41 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AP              
5410: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5420: 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (24<<8)).#define
5430: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45   SQLITE_IOERR_GE
5440: 54 54 45 4d 50 50 41 54 48 20 20 20 20 20 20 20  TTEMPPATH       
5450: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5460: 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (25<<8)).#define
5470: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f   SQLITE_IOERR_CO
5480: 4e 56 50 41 54 48 20 20 20 20 20 20 20 20 20 20  NVPATH          
5490: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
54a0: 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (26<<8)).#define
54b0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53   SQLITE_LOCKED_S
54c0: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
54d0: 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c  (SQLITE_LOCKED |
54e0: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
54f0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45  e SQLITE_BUSY_RE
5500: 43 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20  COVERY          
5510: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20   (SQLITE_BUSY   
5520: 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69  |  (1<<8)).#defi
5530: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 53  ne SQLITE_BUSY_S
5540: 4e 41 50 53 48 4f 54 20 20 20 20 20 20 20 20 20  NAPSHOT         
5550: 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20    (SQLITE_BUSY  
5560: 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 65 66   |  (2<<8)).#def
5570: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
5580: 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20  PEN_NOTEMPDIR   
5590: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
55a0: 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  PEN | (1<<8)).#d
55b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
55c0: 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20  TOPEN_ISDIR     
55d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
55e0: 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a  TOPEN | (2<<8)).
55f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5600: 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48  ANTOPEN_FULLPATH
5610: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5620: 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29  ANTOPEN | (3<<8)
5630: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5640: 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41  _CANTOPEN_CONVPA
5650: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
5660: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c  _CANTOPEN | (4<<
5670: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5680: 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20  TE_CORRUPT_VTAB 
5690: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
56a0: 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c  TE_CORRUPT | (1<
56b0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
56c0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43  ITE_READONLY_REC
56d0: 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c  OVERY       (SQL
56e0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
56f0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5700: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43  QLITE_READONLY_C
5710: 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53  ANTLOCK       (S
5720: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
5730: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5740: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
5750: 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20  _ROLLBACK       
5760: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
5770: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
5780: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5790: 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20 20 20 20  LY_DBMOVED      
57a0: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
57b0: 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  LY | (4<<8)).#de
57c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52  fine SQLITE_ABOR
57d0: 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20  T_ROLLBACK      
57e0: 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f 52      (SQLITE_ABOR
57f0: 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  T | (2<<8)).#def
5800: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5810: 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 20 20  RAINT_CHECK     
5820: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5830: 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a  RAINT | (1<<8)).
5840: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5850: 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54  ONSTRAINT_COMMIT
5860: 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f 43  HOOK   (SQLITE_C
5870: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c  ONSTRAINT | (2<<
5880: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5890: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f  TE_CONSTRAINT_FO
58a0: 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51 4c 49  REIGNKEY   (SQLI
58b0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
58c0: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
58d0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
58e0: 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 28  T_FUNCTION     (
58f0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5900: 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66  T | (4<<8)).#def
5910: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5920: 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20  RAINT_NOTNULL   
5930: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5940: 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a  RAINT | (5<<8)).
5950: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5960: 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d 41 52  ONSTRAINT_PRIMAR
5970: 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43  YKEY   (SQLITE_C
5980: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c  ONSTRAINT | (6<<
5990: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
59a0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52  TE_CONSTRAINT_TR
59b0: 49 47 47 45 52 20 20 20 20 20 20 28 53 51 4c 49  IGGER      (SQLI
59c0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
59d0: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (7<<8)).#define 
59e0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
59f0: 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20 28  T_UNIQUE       (
5a00: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5a10: 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  T | (8<<8)).#def
5a20: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5a30: 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20 20 20  RAINT_VTAB      
5a40: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5a50: 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a  RAINT | (9<<8)).
5a60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5a70: 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49 44 20  ONSTRAINT_ROWID 
5a80: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5a90: 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c  ONSTRAINT |(10<<
5aa0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5ab0: 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45  TE_NOTICE_RECOVE
5ac0: 52 5f 57 41 4c 20 20 20 20 20 20 28 53 51 4c 49  R_WAL      (SQLI
5ad0: 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c  TE_NOTICE | (1<<
5ae0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5af0: 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45  TE_NOTICE_RECOVE
5b00: 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49  R_ROLLBACK (SQLI
5b10: 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c  TE_NOTICE | (2<<
5b20: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5b30: 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49  TE_WARNING_AUTOI
5b40: 4e 44 45 58 20 20 20 20 20 20 20 28 53 51 4c 49  NDEX       (SQLI
5b50: 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c  TE_WARNING | (1<
5b60: 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  <8))../*.** CAPI
5b70: 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20  3REF: Flags For 
5b80: 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74  File Open Operat
5b90: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
5ba0: 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20   bit values are 
5bb0: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
5bc0: 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70   in the.** 3rd p
5bd0: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
5be0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
5bf0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e  ()] interface an
5c00: 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20  d.** in the 4th 
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 76 66 73 2e 78 4f   [sqlite3_vfs.xO
5c30: 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a  pen] method..*/.
5c40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5c50: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  PEN_READONLY    
5c60: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 20       0x00000001 
5c70: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5c80: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5c90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5ca0: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20  PEN_READWRITE   
5cb0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 20       0x00000002 
5cc0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5cd0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5ce0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5cf0: 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20  PEN_CREATE      
5d00: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 20       0x00000004 
5d10: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5d20: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5d30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5d40: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
5d50: 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38 20  E    0x00000008 
5d60: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5d70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5d80: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20  PEN_EXCLUSIVE   
5d90: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 20       0x00000010 
5da0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5db0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5dc0: 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20  PEN_AUTOPROXY   
5dd0: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 20       0x00000020 
5de0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5df0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5e00: 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20  PEN_URI         
5e10: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 20       0x00000040 
5e20: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5e30: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5e40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5e50: 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20  PEN_MEMORY      
5e60: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 20       0x00000080 
5e70: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5e80: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5e90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5ea0: 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20  PEN_MAIN_DB     
5eb0: 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 20       0x00000100 
5ec0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5ed0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5ee0: 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20  PEN_TEMP_DB     
5ef0: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 20       0x00000200 
5f00: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5f10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5f20: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42  PEN_TRANSIENT_DB
5f30: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 20       0x00000400 
5f40: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5f50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5f60: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
5f70: 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30 20       0x00000800 
5f80: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5f90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5fa0: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
5fb0: 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30 20       0x00001000 
5fc0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5fe0: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20  PEN_SUBJOURNAL  
5ff0: 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 20       0x00002000 
6000: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6010: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6020: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
6030: 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 20  AL   0x00004000 
6040: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6050: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6060: 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20  PEN_NOMUTEX     
6070: 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30 20       0x00008000 
6080: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6090: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
60a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
60b0: 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20  PEN_FULLMUTEX   
60c0: 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30 20       0x00010000 
60d0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
60e0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
60f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6100: 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
6110: 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30 20       0x00020000 
6120: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6130: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6140: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6150: 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
6160: 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30 20       0x00040000 
6170: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6180: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6190: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
61a0: 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20  PEN_WAL         
61b0: 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30 20       0x00080000 
61c0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
61d0: 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20  ./* Reserved:   
61e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
61f0: 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30 30        0x00F00000
6200: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
6210: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72  REF: Device Char
6220: 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a  acteristics.**.*
6230: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61  * The xDeviceCha
6240: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
6250: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
6260: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
6270: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
6280: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
6290: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
62a0: 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76  f these.** bit v
62b0: 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67  alues expressing
62c0: 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73   I/O characteris
62d0: 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73  tics of the mass
62e0: 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69   storage.** devi
62f0: 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68  ce that holds th
6300: 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20  e file that the 
6310: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6320: 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74  ods].** refers t
6330: 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  o..**.** The SQL
6340: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6350: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
6360: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
6370: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
6380: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
6390: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
63a0: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
63b0: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
63c0: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
63d0: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
63e0: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
63f0: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
6400: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
6410: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
6420: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
6430: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
6440: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
6450: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
6460: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
6470: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
6480: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
6490: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
64a0: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
64b0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
64c0: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
64d0: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
64e0: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
64f0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6500: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
6510: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
6520: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
6530: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
6540: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
6550: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
6560: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20  ** to xWrite(). 
6570: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6580: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
6590: 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d  WRITE property m
65a0: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74  eans that.** aft
65b0: 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77  er reboot follow
65c0: 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20 70  ing a crash or p
65d0: 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f  ower loss, the o
65e0: 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a  nly bytes in a.*
65f0: 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72 65  * file that were
6600: 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65 20   written at the 
6610: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65  application leve
6620: 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68 61  l might have cha
6630: 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74  nged.** and that
6640: 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c   adjacent bytes,
6650: 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74 68   even bytes with
6660: 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63 74  in the same sect
6670: 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e  or are.** guaran
6680: 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61  teed to be uncha
6690: 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49 54  nged.  The SQLIT
66a0: 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41  E_IOCAP_UNDELETA
66b0: 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a  BLE_WHEN_OPEN.**
66c0: 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 20 74   flag indicate t
66d0: 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f  hat a file canno
66e0: 74 20 62 65 20 64 65 6c 65 74 65 64 20 77 68 65  t be deleted whe
66f0: 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20  n open.  The.** 
6700: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
6710: 55 54 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 69  UTABLE flag indi
6720: 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20 66  cates that the f
6730: 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61  ile is on.** rea
6740: 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64  d-only media and
6750: 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67   cannot be chang
6760: 65 64 20 65 76 65 6e 20 62 79 20 70 72 6f 63 65  ed even by proce
6770: 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65  sses with.** ele
6780: 76 61 74 65 64 20 70 72 69 76 69 6c 65 67 65 73  vated privileges
6790: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
67a0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
67b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
67c0: 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66   0x00000001.#def
67d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
67e0: 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20  _ATOMIC512      
67f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6800: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
6810: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
6820: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6830: 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e  x00000004.#defin
6840: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6850: 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20  TOMIC2K         
6860: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38        0x00000008
6870: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6880: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20  IOCAP_ATOMIC4K  
6890: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
68a0: 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20  0000010.#define 
68b0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
68c0: 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20  MIC8K           
68d0: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23      0x00000020.#
68e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
68f0: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20  CAP_ATOMIC16K   
6900: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6910: 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51  00040.#define SQ
6920: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6930: 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20  C32K            
6940: 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65    0x00000080.#de
6950: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6960: 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20  P_ATOMIC64K     
6970: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6980: 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  100.#define SQLI
6990: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
69a0: 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20  PEND            
69b0: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69  0x00000200.#defi
69c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
69d0: 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20  SEQUENTIAL      
69e0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30         0x0000040
69f0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6a00: 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42  _IOCAP_UNDELETAB
6a10: 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78  LE_WHEN_OPEN  0x
6a20: 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65  00000800.#define
6a30: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f   SQLITE_IOCAP_PO
6a40: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
6a50: 45 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a  E    0x00001000.
6a60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6a70: 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20  OCAP_IMMUTABLE  
6a80: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6a90: 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  002000../*.** CA
6aa0: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
6ab0: 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a  king Levels.**.*
6ac0: 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e  * SQLite uses on
6ad0: 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
6ae0: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
6af0: 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d   second.** argum
6b00: 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20  ent to calls it 
6b10: 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f  makes to the xLo
6b20: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
6b30: 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66  () methods.** of
6b40: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   an [sqlite3_io_
6b50: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
6b60: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
6b70: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20  TE_LOCK_NONE    
6b80: 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
6b90: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
6ba0: 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66  ED        1.#def
6bb0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6bc0: 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a  RESERVED      2.
6bd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6be0: 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20  OCK_PENDING     
6bf0: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
6c00: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
6c10: 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43  E     4../*.** C
6c20: 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f  API3REF: Synchro
6c30: 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c  nization Type Fl
6c40: 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53  ags.**.** When S
6c50: 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68  QLite invokes th
6c60: 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64  e xSync() method
6c70: 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   of an.** [sqlit
6c80: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
6c90: 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20  bject it uses a 
6ca0: 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a  combination of.*
6cb0: 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  * these integer 
6cc0: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
6cd0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  cond argument..*
6ce0: 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51  *.** When the SQ
6cf0: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
6d00: 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c  LY flag is used,
6d10: 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
6d20: 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61  he.** sync opera
6d30: 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20  tion only needs 
6d40: 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f  to flush data to
6d50: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20   mass storage.  
6d60: 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  Inode.** informa
6d70: 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65  tion need not be
6d80: 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65   flushed. If the
6d90: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
6da0: 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20   of the flag.** 
6db0: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
6dc0: 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d  C_NORMAL, that m
6dd0: 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d  eans to use norm
6de0: 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e  al fsync() seman
6df0: 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  tics..** If the 
6e00: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20  lower four bits 
6e10: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
6e20: 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61  C_FULL, that mea
6e30: 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63  ns.** to use Mac
6e40: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
6e50: 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20  sync instead of 
6e60: 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44  fsync()..**.** D
6e70: 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68  o not confuse th
6e80: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
6e90: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
6ea0: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a  SYNC_FULL flags.
6eb0: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41  ** with the [PRA
6ec0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
6ed0: 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41  =NORMAL and [PRA
6ee0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
6ef0: 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67  =FULL.** setting
6f00: 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f  s.  The [synchro
6f10: 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74  nous pragma] det
6f20: 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c  ermines when cal
6f30: 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79  ls to the.** xSy
6f40: 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63  nc VFS method oc
6f50: 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20  cur and applies 
6f60: 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73  uniformly across
6f70: 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a   all platforms..
6f80: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59  ** The SQLITE_SY
6f90: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
6fa0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
6fb0: 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68  lags determine h
6fc0: 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20  ow.** energetic 
6fd0: 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66  or rigorous or f
6fe0: 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63  orceful the sync
6ff0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20   operations are 
7000: 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65  and.** only make
7010: 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e   a difference on
7020: 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65   Mac OSX for the
7030: 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20   default SQLite 
7040: 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d  code..** (Third-
7050: 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d  party VFS implem
7060: 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  entations might 
7070: 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69  also make the di
7080: 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74  stinction.** bet
7090: 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43  ween SQLITE_SYNC
70a0: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
70b0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75  TE_SYNC_FULL, bu
70c0: 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f  t among the.** o
70d0: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73  perating systems
70e0: 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72   natively suppor
70f0: 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f  ted by SQLite, o
7100: 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63  nly Mac OSX.** c
7110: 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64  ares about the d
7120: 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23  ifference.).*/.#
7130: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
7140: 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20  NC_NORMAL       
7150: 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65   0x00002.#define
7160: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
7170: 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  L          0x000
7180: 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  03.#define SQLIT
7190: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
71a0: 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a       0x00010../*
71b0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
71c0: 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20   Interface Open 
71d0: 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  File Handle.**.*
71e0: 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  * An [sqlite3_fi
71f0: 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65  le] object repre
7200: 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69  sents an open fi
7210: 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73  le in the .** [s
7220: 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20  qlite3_vfs | OS 
7230: 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d  interface layer]
7240: 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53  .  Individual OS
7250: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d   interface.** im
7260: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
7270: 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75  ll.** want to su
7280: 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65  bclass this obje
7290: 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20  ct by appending 
72a0: 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
72b0: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f  s.** for their o
72c0: 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65  wn use.  The pMe
72d0: 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61  thods entry is a
72e0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
72f0: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
7300: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68  thods] object th
7310: 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f  at defines metho
7320: 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e  ds for performin
7330: 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69  g.** I/O operati
7340: 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20  ons on the open 
7350: 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  file..*/.typedef
7360: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
7370: 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c  file sqlite3_fil
7380: 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  e;.struct sqlite
7390: 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74  3_file {.  const
73a0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
73b0: 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74  io_methods *pMet
73c0: 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64  hods;  /* Method
73d0: 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69  s for an open fi
73e0: 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  le */.};../*.** 
73f0: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
7400: 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74  erface File Virt
7410: 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65  ual Methods Obje
7420: 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66  ct.**.** Every f
7430: 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68  ile opened by th
7440: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7450: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70  Open] method pop
7460: 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71  ulates an.** [sq
7470: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7480: 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d  ct (or, more com
7490: 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73  monly, a subclas
74a0: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  s of the.** [sql
74b0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
74c0: 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  t) with a pointe
74d0: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
74e0: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e   of this object.
74f0: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
7500: 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68  defines the meth
7510: 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66  ods used to perf
7520: 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72  orm various oper
7530: 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73  ations.** agains
7540: 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20  t the open file 
7550: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74  represented by t
7560: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
7570: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
7580: 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  If the [sqlite3_
7590: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
75a0: 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74  d sets the sqlit
75b0: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
75c0: 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20   element .** to 
75d0: 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
75e0: 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  er, then the sql
75f0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e  ite3_io_methods.
7600: 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a  xClose method.**
7610: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
7620: 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c  even if the [sql
7630: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7640: 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74  reported that it
7650: 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a   failed.  The.**
7660: 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65   only way to pre
7670: 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78  vent a call to x
7680: 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  Close following 
7690: 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65  a failed [sqlite
76a0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20  3_vfs.xOpen].** 
76b0: 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  is for the [sqli
76c0: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74  te3_vfs.xOpen] t
76d0: 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  o set the sqlite
76e0: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
76f0: 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55  element.** to NU
7700: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  LL..**.** The fl
7710: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
7720: 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65  xSync may be one
7730: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43   of [SQLITE_SYNC
7740: 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b  _NORMAL] or.** [
7750: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7760: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68  ].  The first ch
7770: 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d  oice is the norm
7780: 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54  al fsync()..** T
7790: 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65  he second choice
77a0: 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73   is a Mac OS X s
77b0: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20  tyle fullsync.  
77c0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  The [SQLITE_SYNC
77d0: 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c  _DATAONLY].** fl
77e0: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69  ag may be ORed i
77f0: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
7800: 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61  at only the data
7810: 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20   of the file.** 
7820: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64  and not its inod
7830: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79  e needs to be sy
7840: 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nced..**.** The 
7850: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74  integer values t
7860: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  o xLock() and xU
7870: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20  nlock() are one 
7880: 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  of.** <ul>.** <l
7890: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
78a0: 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  NONE],.** <li> [
78b0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
78c0: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
78d0: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
78e0: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
78f0: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
7900: 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  G], or.** <li> [
7910: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
7920: 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  USIVE]..** </ul>
7930: 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72  .** xLock() incr
7940: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20  eases the lock. 
7950: 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61  xUnlock() decrea
7960: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a  ses the lock..**
7970: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72   The xCheckReser
7980: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  vedLock() method
7990: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
79a0: 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e  any database con
79b0: 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68  nection,.** eith
79c0: 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65  er in this proce
79d0: 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74  ss or in some ot
79e0: 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20  her process, is 
79f0: 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56  holding a RESERV
7a00: 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20  ED,.** PENDING, 
7a10: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63  or EXCLUSIVE loc
7a20: 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  k on the file.  
7a30: 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a  It returns true.
7a40: 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63  ** if such a loc
7a50: 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c  k exists and fal
7a60: 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  se otherwise..**
7a70: 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e  .** The xFileCon
7a80: 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73  trol() method is
7a90: 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72   a generic inter
7aa0: 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73  face that allows
7ab0: 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69   custom.** VFS i
7ac0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
7ad0: 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72  o directly contr
7ae0: 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ol an open file 
7af0: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
7b00: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
7b10: 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
7b20: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70    The second "op
7b30: 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  " argument is an
7b40: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f  .** integer opco
7b50: 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  de.  The third a
7b60: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e  rgument is a gen
7b70: 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74  eric pointer int
7b80: 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e  ended to.** poin
7b90: 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65  t to a structure
7ba0: 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69   that may contai
7bb0: 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73  n arguments or s
7bc0: 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f  pace in which to
7bd0: 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e  .** write return
7be0: 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74   values.  Potent
7bf0: 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69  ial uses for xFi
7c00: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68  leControl() migh
7c10: 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  t be.** function
7c20: 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63  s to enable bloc
7c30: 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20  king locks with 
7c40: 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61  timeouts, to cha
7c50: 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69  nge the.** locki
7c60: 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72  ng strategy (for
7c70: 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20   example to use 
7c80: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c  dot-file locks),
7c90: 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61   to inquire.** a
7ca0: 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20  bout the status 
7cb0: 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f  of a lock, or to
7cc0: 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63   break stale loc
7cd0: 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a  ks.  The SQLite.
7ce0: 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73  ** core reserves
7cf0: 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73   all opcodes les
7d00: 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69  s than 100 for i
7d10: 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41  ts own use..** A
7d20: 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f   [file control o
7d30: 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66  pcodes | list of
7d40: 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74   opcodes] less t
7d50: 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c  han 100 is avail
7d60: 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  able..** Applica
7d70: 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e  tions that defin
7d80: 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65  e a custom xFile
7d90: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73  Control method s
7da0: 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65  hould use opcode
7db0: 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61  s.** greater tha
7dc0: 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63  n 100 to avoid c
7dd0: 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69  onflicts.  VFS i
7de0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
7df0: 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
7e00: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
7e10: 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72  ] for file contr
7e20: 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20  ol opcodes that 
7e30: 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72  they do not.** r
7e40: 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20  ecognize..**.** 
7e50: 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28  The xSectorSize(
7e60: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
7e70: 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   the sector size
7e80: 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63   of the.** devic
7e90: 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73  e that underlies
7ea0: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
7eb0: 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74  sector size is t
7ec0: 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72  he.** minimum wr
7ed0: 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20  ite that can be 
7ee0: 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75  performed withou
7ef0: 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20  t disturbing.** 
7f00: 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74  other bytes in t
7f10: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44  he file.  The xD
7f20: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
7f30: 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  tics().** method
7f40: 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76   returns a bit v
7f50: 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67  ector describing
7f60: 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68   behaviors of th
7f70: 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20  e.** underlying 
7f80: 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75  device:.**.** <u
7f90: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
7fa0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d  TE_IOCAP_ATOMIC]
7fb0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7fc0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
7fd0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
7fe0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
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 32 4b  E_IOCAP_ATOMIC2K
8010: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8020: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
8030: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8040: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
8050: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8060: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
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 33  TE_IOCAP_ATOMIC3
8090: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
80a0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
80b0: 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  64K].** <li> [SQ
80c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
80d0: 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20  APPEND].** <li> 
80e0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45  [SQLITE_IOCAP_SE
80f0: 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75  QUENTIAL].** </u
8100: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  l>.**.** The SQL
8110: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8120: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
8130: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
8140: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
8150: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
8160: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8170: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
8180: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
8190: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
81a0: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
81b0: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
81c0: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
81d0: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
81e0: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
81f0: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
8200: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
8210: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
8220: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
8230: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
8240: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
8250: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
8260: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
8270: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
8280: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
8290: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
82a0: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
82b0: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
82c0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
82d0: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
82e0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
82f0: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
8300: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
8310: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
8320: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
8330: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a  ** to xWrite()..
8340: 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29  **.** If xRead()
8350: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
8360: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
8370: 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69   it must also fi
8380: 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72  ll.** in the unr
8390: 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20  ead portions of 
83a0: 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20  the buffer with 
83b0: 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68  zeros.  A VFS th
83c0: 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a  at.** fails to z
83d0: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
83e0: 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20  eads might seem 
83f0: 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65  to work.  Howeve
8400: 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f  r,.** failure to
8410: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
8420: 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e   reads will even
8430: 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a  tually lead to.*
8440: 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75  * database corru
8450: 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  ption..*/.typede
8460: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
8470: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  _io_methods sqli
8480: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a  te3_io_methods;.
8490: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
84a0: 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e  o_methods {.  in
84b0: 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e  t iVersion;.  in
84c0: 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69  t (*xClose)(sqli
84d0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
84e0: 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74  t (*xRead)(sqlit
84f0: 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c  e3_file*, void*,
8500: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
8510: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
8520: 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29  .  int (*xWrite)
8530: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8540: 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
8550: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
8560: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
8570: 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28  nt (*xTruncate)(
8580: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8590: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a  qlite3_int64 siz
85a0: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e  e);.  int (*xSyn
85b0: 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  c)(sqlite3_file*
85c0: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
85d0: 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29  int (*xFileSize)
85e0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
85f0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70  sqlite3_int64 *p
8600: 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Size);.  int (*x
8610: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
8620: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
8630: 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69   (*xUnlock)(sqli
8640: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
8650: 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52  .  int (*xCheckR
8660: 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c  eservedLock)(sql
8670: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8680: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
8690: 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29   (*xFileControl)
86a0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
86b0: 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41  int op, void *pA
86c0: 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65  rg);.  int (*xSe
86d0: 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65  ctorSize)(sqlite
86e0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
86f0: 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74  (*xDeviceCharact
8700: 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65  eristics)(sqlite
8710: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d  3_file*);.  /* M
8720: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8730: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8740: 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 1 */.  int (*
8750: 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33  xShmMap)(sqlite3
8760: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c  _file*, int iPg,
8770: 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20   int pgsz, int, 
8780: 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29  void volatile**)
8790: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f  ;.  int (*xShmLo
87a0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
87b0: 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69  *, int offset, i
87c0: 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29  nt n, int flags)
87d0: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42  ;.  void (*xShmB
87e0: 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f  arrier)(sqlite3_
87f0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8800: 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74  xShmUnmap)(sqlit
8810: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65  e3_file*, int de
8820: 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20  leteFlag);.  /* 
8830: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
8840: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
8850: 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28  ion 2 */.  int (
8860: 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33  *xFetch)(sqlite3
8870: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
8880: 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74  int64 iOfst, int
8890: 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70   iAmt, void **pp
88a0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65  );.  int (*xUnfe
88b0: 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  tch)(sqlite3_fil
88c0: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
88d0: 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70  4 iOfst, void *p
88e0: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
88f0: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
8900: 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f  for version 3 */
8910: 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c  .  /* Additional
8920: 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20   methods may be 
8930: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
8940: 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a  releases */.};..
8950: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
8960: 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f  Standard File Co
8970: 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a  ntrol Opcodes.**
8980: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65   KEYWORDS: {file
8990: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73   control opcodes
89a0: 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  } {file control 
89b0: 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68  opcode}.**.** Th
89c0: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
89d0: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
89e0: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
89f0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
8a00: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
8a10: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
8a20: 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20  ect and for the 
8a30: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
8a40: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65  ntrol()].** inte
8a50: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rface..**.** The
8a60: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
8a70: 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65  OCKSTATE] opcode
8a80: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
8a90: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
8aa0: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
8ab0: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
8ac0: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20  method to write 
8ad0: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
8ae0: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b  e of.** the lock
8af0: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45   (one of [SQLITE
8b00: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51  _LOCK_NONE], [SQ
8b10: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
8b20: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f  ],.** [SQLITE_LO
8b30: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53  CK_RESERVED], [S
8b40: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
8b50: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  NG], or [SQLITE_
8b60: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29  LOCK_EXCLUSIVE])
8b70: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65  .** into an inte
8b80: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72  ger that the pAr
8b90: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  g argument point
8ba0: 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62  s to. This capab
8bb0: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64  ility.** is used
8bc0: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
8bd0: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
8be0: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
8bf0: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a  hen SQLITE_TEST.
8c00: 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a  ** is defined..*
8c10: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b  * <ul>.** <li>[[
8c20: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
8c30: 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20  E_HINT]].** The 
8c40: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
8c50: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20  ZE_HINT] opcode 
8c60: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  is used by SQLit
8c70: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46  e to give the VF
8c80: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e  S.** layer a hin
8c90: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74  t of how large t
8ca0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
8cb0: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65   will grow to be
8cc0: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63   during the.** c
8cd0: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
8ce0: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69  on.  This hint i
8cf0: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64  s not guaranteed
8d00: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20   to be accurate 
8d10: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74  but it.** is oft
8d20: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75  en close.  The u
8d30: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69  nderlying VFS mi
8d40: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72  ght choose to pr
8d50: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61  eallocate databa
8d60: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65  se.** file space
8d70: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68   based on this h
8d80: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  int in order to 
8d90: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74  help writes to t
8da0: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  he database.** f
8db0: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a  ile run faster..
8dc0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
8dd0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
8de0: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  IZE]].** The [SQ
8df0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
8e00: 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73  _SIZE] opcode is
8e10: 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74   used to request
8e20: 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a   that the VFS.**
8e30: 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75   extends and tru
8e40: 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62  ncates the datab
8e50: 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e  ase file in chun
8e60: 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65  ks of a size spe
8e70: 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
8e80: 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74   user. The fourt
8e90: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  h argument to [s
8ea0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
8eb0: 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a  rol()] should .*
8ec0: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e  * point to an in
8ed0: 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29  teger (type int)
8ee0: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
8ef0: 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74  new chunk-size t
8f00: 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65  o use.** for the
8f10: 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62   nominated datab
8f20: 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20  ase. Allocating 
8f30: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70  database file sp
8f40: 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20  ace in large.** 
8f50: 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20  chunks (say 1MB 
8f60: 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20  at a time), may 
8f70: 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74  reduce file-syst
8f80: 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e  em fragmentation
8f90: 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20   and.** improve 
8fa0: 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73  performance on s
8fb0: 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a  ome systems..**.
8fc0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
8fd0: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
8fe0: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ER]].** The [SQL
8ff0: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
9000: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
9010: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
9020: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
9030: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
9040: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
9050: 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72  iated with a par
9060: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
9070: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
9080: 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65   See the [sqlite
9090: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
90a0: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
90b0: 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
90c0: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
90d0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
90e0: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
90f0: 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e  TTED]].** No lon
9100: 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a  ger in use..**.*
9110: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9120: 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54  CNTL_SYNC]].** T
9130: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9140: 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73  _SYNC] opcode is
9150: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72   generated inter
9160: 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20  nally by SQLite 
9170: 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74  and.** sent to t
9180: 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74 65  he VFS immediate
9190: 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20 78 53  ly before the xS
91a0: 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  ync method is in
91b0: 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61  voked on a.** da
91c0: 74 61 62 61 73 65 20 66 69 6c 65 20 64 65 73 63  tabase file desc
91d0: 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74  riptor. Or, if t
91e0: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20  he xSync method 
91f0: 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a  is not invoked .
9200: 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65 20 75  ** because the u
9210: 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75 72  ser has configur
9220: 65 64 20 53 51 4c 69 74 65 20 77 69 74 68 20 0a  ed SQLite with .
9230: 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  ** [PRAGMA synch
9240: 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20  ronous | PRAGMA 
9250: 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d  synchronous=OFF]
9260: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 69   it is invoked i
9270: 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74  n place .** of t
9280: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e  he xSync method.
9290: 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c 20   In most cases, 
92a0: 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  the pointer argu
92b0: 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69 74 68  ment passed with
92c0: 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  .** this file-co
92d0: 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48  ntrol is NULL. H
92e0: 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65 20 64  owever, if the d
92f0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
9300: 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20  being synced.** 
9310: 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75 6c  as part of a mul
9320: 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d 6d  ti-database comm
9330: 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e 74  it, the argument
9340: 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c   points to a nul
9350: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
9360: 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67  tring containing
9370: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
9380: 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c  s master-journal
9390: 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65   file name. VFSe
93a0: 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f  s that .** do no
93b0: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  t need this sign
93c0: 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74  al should silent
93d0: 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f  ly ignore this o
93e0: 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69  pcode. Applicati
93f0: 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  ons .** should n
9400: 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  ot call [sqlite3
9410: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
9420: 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64   with this opcod
9430: 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61  e as doing so ma
9440: 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74 68  y .** disrupt th
9450: 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74  e operation of t
9460: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56  he specialized V
9470: 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71  FSes that do req
9480: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a  uire it.  .**.**
9490: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
94a0: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
94b0: 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TWO]].** The [SQ
94c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
94d0: 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f  T_PHASETWO] opco
94e0: 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20  de is generated 
94f0: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51  internally by SQ
9500: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74  Lite.** and sent
9510: 20 74 6f 20 74 68 65 20 56 46 53 20 61 66 74 65   to the VFS afte
9520: 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
9530: 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74  has been committ
9540: 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a  ed immediately.*
9550: 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74 68 65  * but before the
9560: 20 64 61 74 61 62 61 73 65 20 69 73 20 75 6e 6c   database is unl
9570: 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68 61  ocked. VFSes tha
9580: 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68  t do not need th
9590: 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f  is signal.** sho
95a0: 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e  uld silently ign
95b0: 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  ore this opcode.
95c0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
95d0: 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a  ould not call.**
95e0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
95f0: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
9600: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f  his opcode as do
9610: 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75  ing so may disru
9620: 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61  pt the .** opera
9630: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
9640: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68  ialized VFSes th
9650: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
9660: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
9670: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
9680: 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a  32_AV_RETRY]].**
9690: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
96a0: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
96b0: 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  RY] opcode is us
96c0: 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20  ed to configure 
96d0: 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74  automatic.** ret
96e0: 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e  ry counts and in
96f0: 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74  tervals for cert
9700: 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65  ain disk I/O ope
9710: 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a  rations for the.
9720: 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d  ** windows [VFS]
9730: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f   in order to pro
9740: 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20  vide robustness 
9750: 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  in the presence 
9760: 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73  of.** anti-virus
9770: 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64   programs.  By d
9780: 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64  efault, the wind
9790: 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74  ows VFS will ret
97a0: 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a  ry file read,.**
97b0: 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64   file write, and
97c0: 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65   file delete ope
97d0: 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30  rations up to 10
97e0: 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64   times, with a d
97f0: 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69  elay.** of 25 mi
9800: 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72  lliseconds befor
9810: 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74 72  e the first retr
9820: 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20 64  y and with the d
9830: 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a  elay increasing.
9840: 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f  ** by an additio
9850: 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f  nal 25 milliseco
9860: 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73 75  nds with each su
9870: 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20  bsequent retry. 
9880: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
9890: 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f  allows these two
98a0: 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74 72   values (10 retr
98b0: 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69  ies and 25 milli
98c0: 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79  seconds of delay
98d0: 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73  ).** to be adjus
98e0: 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73  ted.  The values
98f0: 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72   are changed for
9900: 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f   all database co
9910: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74  nnections.** wit
9920: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f  hin the same pro
9930: 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d  cess.  The argum
9940: 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
9950: 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20   to an array of 
9960: 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20  two.** integers 
9970: 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74 20  where the first 
9980: 69 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e 65  integer i the ne
9990: 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e  w retry count an
99a0: 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  d the second.** 
99b0: 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 64  integer is the d
99c0: 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65 72  elay.  If either
99d0: 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61   integer is nega
99e0: 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73  tive, then the s
99f0: 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74  etting.** is not
9a00: 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73   changed but ins
9a10: 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20 76  tead the prior v
9a20: 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65 74  alue of that set
9a30: 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a  ting is written.
9a40: 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61  ** into the arra
9a50: 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e  y entry, allowin
9a60: 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65  g the current re
9a70: 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20  try settings to 
9a80: 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74  be.** interrogat
9a90: 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65  ed.  The zDbName
9aa0: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 67   parameter is ig
9ab0: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  nored..**.** <li
9ac0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9ad0: 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a  PERSIST_WAL]].**
9ae0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
9af0: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d  NTL_PERSIST_WAL]
9b00: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
9b10: 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20  to set or query 
9b20: 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e  the.** persisten
9b30: 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41  t [WAL | Write A
9b40: 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e  head Log] settin
9b50: 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  g.  By default, 
9b60: 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a  the auxiliary.**
9b70: 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67   write ahead log
9b80: 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f   and shared memo
9b90: 72 79 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f  ry files used fo
9ba0: 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f  r transaction co
9bb0: 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74  ntrol.** are aut
9bc0: 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
9bd0: 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65  ed when the late
9be0: 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  st connection to
9bf0: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
9c00: 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e   closes.  Settin
9c10: 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c  g persistent WAL
9c20: 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f   mode causes tho
9c30: 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73  se files to pers
9c40: 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f  ist after.** clo
9c50: 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20  se.  Persisting 
9c60: 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73 65  the files is use
9c70: 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70  ful when other p
9c80: 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64 6f  rocesses that do
9c90: 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69   not.** have wri
9ca0: 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e  te permission on
9cb0: 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 63   the directory c
9cc0: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61  ontaining the da
9cd0: 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74  tabase file want
9ce0: 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20  .** to read the 
9cf0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61  database file, a
9d00: 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68  s the WAL and sh
9d10: 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65  ared memory file
9d20: 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20  s must exist.** 
9d30: 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65  in order for the
9d40: 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   database to be 
9d50: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66  readable.  The f
9d60: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
9d70: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
9d80: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66  ile_control()] f
9d90: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73  or this opcode s
9da0: 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74  hould be a point
9db0: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
9dc0: 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65  ..** That intege
9dd0: 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  r is 0 to disabl
9de0: 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c  e persistent WAL
9df0: 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e   mode or 1 to en
9e00: 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a  able persistent.
9e10: 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66  ** WAL mode.  If
9e20: 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20   the integer is 
9e30: 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f  -1, then it is o
9e40: 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20  verwritten with 
9e50: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57  the current.** W
9e60: 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20 73  AL persistence s
9e70: 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  etting..**.** <l
9e80: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9e90: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
9ea0: 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  RITE]].** ^The [
9eb0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
9ec0: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
9ed0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9ee0: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79   to set or query
9ef0: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65   the.** persiste
9f00: 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76  nt "powersafe-ov
9f10: 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f  erwrite" or "PSO
9f20: 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65  W" setting.  The
9f30: 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a   PSOW setting.**
9f40: 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20   determines the 
9f50: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f  [SQLITE_IOCAP_PO
9f60: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
9f70: 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a  E] bit of the.**
9f80: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
9f90: 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e  ristics methods.
9fa0: 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
9fb0: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
9fc0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
9fd0: 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70  l()] for this op
9fe0: 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61  code should be a
9ff0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
a000: 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20  nteger..** That 
a010: 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20  integer is 0 to 
a020: 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d  disable zero-dam
a030: 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f  age mode or 1 to
a040: 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d   enable zero-dam
a050: 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66  age.** mode.  If
a060: 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20   the integer is 
a070: 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f  -1, then it is o
a080: 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20  verwritten with 
a090: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a  the current.** z
a0a0: 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20  ero-damage mode 
a0b0: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c  setting..**.** <
a0c0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
a0d0: 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a  L_OVERWRITE]].**
a0e0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
a0f0: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f  NTL_OVERWRITE] o
a100: 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64  pcode is invoked
a110: 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65 72   by SQLite after
a120: 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72   opening.** a wr
a130: 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  ite transaction 
a140: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
a150: 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72  , unless it is r
a160: 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73  olled back for s
a170: 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74  ome.** reason, t
a180: 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62 61  he entire databa
a190: 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  se file will be 
a1a0: 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74  overwritten by t
a1b0: 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74  he current .** t
a1c0: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73  ransaction. This
a1d0: 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43 55   is used by VACU
a1e0: 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  UM operations..*
a1f0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
a200: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d  E_FCNTL_VFSNAME]
a210: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
a220: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d  E_FCNTL_VFSNAME]
a230: 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75   opcode can be u
a240: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  sed to obtain th
a250: 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c  e names of.** al
a260: 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65  l [VFSes] in the
a270: 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65   VFS stack.  The
a280: 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c   names are of al
a290: 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20  l VFS shims and 
a2a0: 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74  the.** final bot
a2b0: 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72  tom-level VFS ar
a2c0: 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d  e written into m
a2d0: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
a2e0: 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rom .** [sqlite3
a2f0: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74  _malloc()] and t
a300: 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f  he result is sto
a310: 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a  red in the char*
a320: 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61   variable.** tha
a330: 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  t the fourth par
a340: 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74  ameter of [sqlit
a350: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
a360: 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a  )] points to..**
a370: 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72   The caller is r
a380: 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66  esponsible for f
a390: 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72  reeing the memor
a3a0: 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73  y when done.  As
a3b0: 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c   with.** all fil
a3c0: 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e  e-control action
a3d0: 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67  s, there is no g
a3e0: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
a3f0: 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79  is will actually
a400: 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e  .** do anything.
a410: 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64    Callers should
a420: 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   initialize the 
a430: 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74  char* variable t
a440: 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  o a NULL.** poin
a450: 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69 73  ter in case this
a460: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
a470: 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64   not implemented
a480: 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e  .  This file-con
a490: 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e  trol.** is inten
a4a0: 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74  ded for diagnost
a4b0: 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a  ic use only..**.
a4c0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
a4d0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a  FCNTL_PRAGMA]].*
a4e0: 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50  * ^Whenever a [P
a4f0: 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74  RAGMA] statement
a500: 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b   is parsed, an [
a510: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
a520: 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f  GMA] .** file co
a530: 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f  ntrol is sent to
a540: 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74   the open [sqlit
a550: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
a560: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
a570: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
a580: 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74   file to which t
a590: 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  he pragma statem
a5a0: 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65  ent refers. ^The
a5b0: 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
a5c0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
a5d0: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
a5e0: 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72  ontrol is an arr
a5f0: 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72  ay of.** pointer
a600: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68  s to strings (ch
a610: 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74  ar**) in which t
a620: 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e  he second elemen
a630: 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a  t of the array.*
a640: 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
a650: 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20   the pragma and 
a660: 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e  the third elemen
a670: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
a680: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67  t to the.** prag
a690: 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  ma or NULL if th
a6a0: 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20  e pragma has no 
a6b0: 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20  argument.  ^The 
a6c0: 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a  handler for an.*
a6d0: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
a6e0: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
a6f0: 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61  trol can optiona
a700: 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72  lly make the fir
a710: 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66  st element.** of
a720: 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75   the char** argu
a730: 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20  ment point to a 
a740: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20  string obtained 
a750: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70  from [sqlite3_mp
a760: 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74  rintf()].** or t
a770: 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e  he equivalent an
a780: 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69  d that string wi
a790: 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65  ll become the re
a7a0: 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67  sult of the prag
a7b0: 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72  ma or.** the err
a7c0: 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68  or message if th
a7d0: 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20  e pragma fails. 
a7e0: 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
a7f0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a800: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
a810: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f  turns [SQLITE_NO
a820: 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f  TFOUND], then no
a830: 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41  rmal .** [PRAGMA
a840: 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e  ] processing con
a850: 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65  tinues.  ^If the
a860: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
a870: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63  RAGMA].** file c
a880: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b  ontrol returns [
a890: 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e  SQLITE_OK], then
a8a0: 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75   the parser assu
a8b0: 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
a8c0: 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20  VFS has handled 
a8d0: 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c  the PRAGMA itsel
a8e0: 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72  f and the parser
a8f0: 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d   generates a no-
a900: 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  op.** prepared s
a910: 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49 66 20 74  tatement.  ^If t
a920: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a930: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
a940: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a  ntrol returns.**
a950: 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65   any result code
a960: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
a970: 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49  ITE_OK] or [SQLI
a980: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68  TE_NOTFOUND], th
a990: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  at means.** that
a9a0: 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74   the VFS encount
a9b0: 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68  ered an error wh
a9c0: 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65  ile handling the
a9d0: 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68   [PRAGMA] and th
a9e0: 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e  e.** compilation
a9f0: 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20 66   of the PRAGMA f
aa00: 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72  ails with an err
aa10: 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  or.  ^The [SQLIT
aa20: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
aa30: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
aa40: 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62 65  occurs at the be
aa50: 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d  ginning of pragm
aa60: 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c  a statement anal
aa70: 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69  ysis and so.** i
aa80: 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65  t is able to ove
aa90: 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b  rride built-in [
aaa0: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
aab0: 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ts..**.** <li>[[
aac0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
aad0: 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54  YHANDLER]].** ^T
aae0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
aaf0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a  _BUSYHANDLER].**
ab00: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61   file-control ma
ab10: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20  y be invoked by 
ab20: 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61  SQLite on the da
ab30: 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64  tabase file hand
ab40: 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66  le.** shortly af
ab50: 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64  ter it is opened
ab60: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f   in order to pro
ab70: 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46  vide a custom VF
ab80: 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a  S with access.**
ab90: 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69   to the connecti
aba0: 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72  ons busy-handler
abb0: 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61   callback. The a
abc0: 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79  rgument is of ty
abd0: 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20  pe (void **).** 
abe0: 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77  - an array of tw
abf0: 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65  o (void *) value
ac00: 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76 6f  s. The first (vo
ac10: 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70  id *) actually p
ac20: 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75  oints.** to a fu
ac30: 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28  nction of type (
ac40: 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29  int (*)(void *))
ac50: 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  . In order to in
ac60: 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74  voke the connect
ac70: 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e  ions.** busy-han
ac80: 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74  dler, this funct
ac90: 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e  ion should be in
aca0: 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20 73  voked with the s
acb0: 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69  econd (void *) i
acc0: 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61  n.** the array a
acd0: 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d  s the only argum
ace0: 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75 72  ent. If it retur
acf0: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
ad00: 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  n the operation.
ad10: 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
ad20: 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74 75  ried. If it retu
ad30: 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75  rns zero, the cu
ad40: 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20  stom VFS should 
ad50: 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63  abandon the.** c
ad60: 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e  urrent operation
ad70: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
ad80: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
ad90: 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70  ILENAME]].** ^Ap
ada0: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e  plication can in
adb0: 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 45  voke the [SQLITE
adc0: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
add0: 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  AME] file-contro
ade0: 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 4c  l.** to have SQL
adf0: 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a  ite generate a.*
ae00: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
ae10: 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73  name using the s
ae20: 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68  ame algorithm th
ae30: 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74  at is followed t
ae40: 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65  o generate.** te
ae50: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65  mporary filename
ae60: 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65  s for TEMP table
ae70: 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65  s and other inte
ae80: 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a  rnal uses.  The.
ae90: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
aea0: 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77  ld be a char** w
aeb0: 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c  hich will be fil
aec0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69 6c  led with the fil
aed0: 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e  ename.** written
aee0: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
aef0: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
af00: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20  te3_malloc()].  
af10: 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c  The caller shoul
af20: 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  d.** invoke [sql
af30: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20  ite3_free()] on 
af40: 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76  the result to av
af50: 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61  oid a memory lea
af60: 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  k..**.** <li>[[S
af70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
af80: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SIZE]].** The [
af90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
afa0: 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e  P_SIZE] file con
afb0: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f 20  trol is used to 
afc0: 71 75 65 72 79 20 6f 72 20 73 65 74 20 74 68 65  query or set the
afd0: 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  .** maximum numb
afe0: 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 61 74  er of bytes that
aff0: 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66 6f   will be used fo
b000: 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20  r memory-mapped 
b010: 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  I/O..** The argu
b020: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
b030: 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 20  r to a value of 
b040: 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  type sqlite3_int
b050: 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e  64 that.** is an
b060: 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d 75   advisory maximu
b070: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  m number of byte
b080: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74 6f  s in the file to
b090: 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68   memory map.  Th
b0a0: 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20  e.** pointer is 
b0b0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
b0c0: 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20   the old value. 
b0d0: 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f   The limit is no
b0e0: 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20  t changed if.** 
b0f0: 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69 6e  the value origin
b100: 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f 20  ally pointed to 
b110: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e 64  is negative, and
b120: 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   so the current 
b130: 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65  limit .** can be
b140: 20 71 75 65 72 69 65 64 20 62 79 20 70 61 73 73   queried by pass
b150: 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 72  ing in a pointer
b160: 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20 6e   to a negative n
b170: 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20  umber.  This.** 
b180: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
b190: 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
b1a0: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52  to implement [PR
b1b0: 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e  AGMA mmap_size].
b1c0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b1d0: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  ITE_FCNTL_TRACE]
b1e0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
b1f0: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69  _FCNTL_TRACE] fi
b200: 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69  le control provi
b210: 64 65 73 20 61 64 76 69 73 6f 72 79 20 69 6e 66  des advisory inf
b220: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74  ormation.** to t
b230: 68 65 20 56 46 53 20 61 62 6f 75 74 20 77 68 61  he VFS about wha
b240: 74 20 74 68 65 20 68 69 67 68 65 72 20 6c 61 79  t the higher lay
b250: 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ers of the SQLit
b260: 65 20 73 74 61 63 6b 20 61 72 65 20 64 6f 69 6e  e stack are doin
b270: 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20  g..** This file 
b280: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
b290: 62 79 20 73 6f 6d 65 20 56 46 53 20 61 63 74 69  by some VFS acti
b2a0: 76 69 74 79 20 74 72 61 63 69 6e 67 20 5b 73 68  vity tracing [sh
b2b0: 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ims]..** The arg
b2c0: 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d  ument is a zero-
b2d0: 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
b2e0: 67 2e 20 20 48 69 67 68 65 72 20 6c 61 79 65 72  g.  Higher layer
b2f0: 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69  s in the.** SQLi
b300: 74 65 20 73 74 61 63 6b 20 6d 61 79 20 67 65 6e  te stack may gen
b310: 65 72 61 74 65 20 69 6e 73 74 61 6e 63 65 73 20  erate instances 
b320: 6f 66 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e  of this file con
b330: 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b  trol if.** the [
b340: 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c  SQLITE_USE_FCNTL
b350: 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d  _TRACE] compile-
b360: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65  time option is e
b370: 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  nabled..**.** <l
b380: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b390: 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20  _HAS_MOVED]].** 
b3a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b3b0: 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c  L_HAS_MOVED] fil
b3c0: 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70  e control interp
b3d0: 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e  rets its argumen
b3e0: 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  t as a.** pointe
b3f0: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
b400: 61 6e 64 20 69 74 20 77 72 69 74 65 73 20 61 20  and it writes a 
b410: 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61  boolean into tha
b420: 74 20 69 6e 74 65 67 65 72 20 64 65 70 65 6e 64  t integer depend
b430: 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  ing.** on whethe
b440: 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 6c  r or not the fil
b450: 65 20 68 61 73 20 62 65 65 6e 20 72 65 6e 61 6d  e has been renam
b460: 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65  ed, moved, or de
b470: 6c 65 74 65 64 20 73 69 6e 63 65 20 69 74 0a 2a  leted since it.*
b480: 2a 20 77 61 73 20 66 69 72 73 74 20 6f 70 65 6e  * was first open
b490: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
b4a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
b4b0: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a  32_SET_HANDLE]].
b4c0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
b4d0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
b4e0: 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73  ANDLE] opcode is
b4f0: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
b500: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
b510: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
b520: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
b530: 68 6f 64 20 74 6f 20 73 77 61 70 20 74 68 65 20  hod to swap the 
b540: 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 69 74 68  file handle with
b550: 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e   the one.** poin
b560: 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 70 41  ted to by the pA
b570: 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68  rg argument.  Th
b580: 69 73 20 63 61 70 61 62 69 6c 69 74 79 20 69 73  is capability is
b590: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
b5a0: 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ting.** and only
b5b0: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70   needs to be sup
b5c0: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49  ported when SQLI
b5d0: 54 45 5f 54 45 53 54 20 69 73 20 64 65 66 69 6e  TE_TEST is defin
b5e0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a  ed..**.** </ul>.
b5f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
b600: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
b610: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
b620: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
b630: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
b640: 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20 32  LE             2
b650: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b660: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
b670: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a  E             3.
b680: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
b690: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20  AST_ERRNO       
b6a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23               4.#
b6b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b6c0: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20  NTL_SIZE_HINT   
b6d0: 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
b6e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b6f0: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20  TL_CHUNK_SIZE   
b700: 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
b710: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b720: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20  L_FILE_POINTER  
b730: 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
b740: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b750: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20  _SYNC_OMITTED   
b760: 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69           8.#defi
b770: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b780: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20  WIN32_AV_RETRY  
b790: 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e          9.#defin
b7a0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
b7b0: 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20  ERSIST_WAL      
b7c0: 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65        10.#define
b7d0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56   SQLITE_FCNTL_OV
b7e0: 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20  ERWRITE         
b7f0: 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20       11.#define 
b800: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
b810: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20  NAME            
b820: 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53      12.#define S
b830: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
b840: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
b850: 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51     13.#define SQ
b860: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
b870: 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
b880: 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c    14.#define SQL
b890: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
b8a0: 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 20  NDLER           
b8b0: 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   15.#define SQLI
b8c0: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c  TE_FCNTL_TEMPFIL
b8d0: 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20  ENAME           
b8e0: 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  16.#define SQLIT
b8f0: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
b900: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31  E              1
b910: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
b920: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20  _FCNTL_TRACE    
b930: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39                19
b940: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b950: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20  FCNTL_HAS_MOVED 
b960: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 0a               20.
b970: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b980: 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20 20 20  CNTL_SYNC       
b990: 20 20 20 20 20 20 20 20 20 20 20 20 32 31 0a 23              21.#
b9a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b9b0: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
b9c0: 54 57 4f 20 20 20 20 20 20 20 20 32 32 0a 23 64  TWO        22.#d
b9d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b9e0: 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e  TL_WIN32_SET_HAN
b9f0: 44 4c 45 20 20 20 20 20 20 20 32 33 0a 0a 2f 2a  DLE       23../*
ba00: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
ba10: 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  tex Handle.**.**
ba20: 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c   The mutex modul
ba30: 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20  e within SQLite 
ba40: 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33  defines [sqlite3
ba50: 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e  _mutex] to be an
ba60: 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70  .** abstract typ
ba70: 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62  e for a mutex ob
ba80: 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74  ject.  The SQLit
ba90: 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f  e core never loo
baa0: 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74  ks.** at the int
bab0: 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
bac0: 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69  tion of an [sqli
bad0: 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20  te3_mutex].  It 
bae0: 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69  only.** deals wi
baf0: 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  th pointers to t
bb00: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
bb10: 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  x] object..**.**
bb20: 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65   Mutexes are cre
bb30: 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
bb40: 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
bb50: 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
bb60: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75  truct sqlite3_mu
bb70: 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  tex sqlite3_mute
bb80: 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  x;../*.** CAPI3R
bb90: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
bba0: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e   Object.**.** An
bbb0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
bbc0: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
bbd0: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
bbe0: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
bbf0: 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20  n.** the SQLite 
bc00: 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64  core and the und
bc10: 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e  erlying operatin
bc20: 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22  g system.  The "
bc30: 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  vfs".** in the n
bc40: 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63  ame of the objec
bc50: 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69  t stands for "vi
bc60: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
bc70: 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20  m".  See.** the 
bc80: 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d  [VFS | VFS docum
bc90: 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75  entation] for fu
bca0: 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f  rther informatio
bcb0: 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c  n..**.** The val
bcc0: 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69  ue of the iVersi
bcd0: 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74  on field is init
bce0: 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20  ially 1 but may 
bcf0: 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20  be larger in.** 
bd00: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
bd10: 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69  of SQLite.  Addi
bd20: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61  tional fields ma
bd30: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f  y be appended to
bd40: 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20   this.** object 
bd50: 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f  when the iVersio
bd60: 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65  n value is incre
bd70: 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74  ased.  Note that
bd80: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a   the structure.*
bd90: 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
bda0: 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e  _vfs object chan
bdb0: 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73  ges in the trans
bdc0: 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a  action between.*
bdd0: 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
bde0: 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30   3.5.9 and 3.6.0
bdf0: 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65   and yet the iVe
be00: 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20  rsion field was 
be10: 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e  not.** modified.
be20: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46  .**.** The szOsF
be30: 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65  ile field is the
be40: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62   size of the sub
be50: 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33  classed [sqlite3
be60: 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74  _file].** struct
be70: 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73  ure used by this
be80: 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d   VFS.  mxPathnam
be90: 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  e is the maximum
bea0: 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20   length of.** a 
beb0: 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73  pathname in this
bec0: 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69   VFS..**.** Regi
bed0: 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76  stered sqlite3_v
bee0: 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b  fs objects are k
bef0: 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20  ept on a linked 
bf00: 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a  list formed by.*
bf10: 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  * the pNext poin
bf20: 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ter.  The [sqlit
bf30: 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28  e3_vfs_register(
bf40: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
bf50: 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
bf60: 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  r()] interfaces 
bf70: 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74  manage this list
bf80: 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d  .** in a thread-
bf90: 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b  safe way.  The [
bfa0: 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64  sqlite3_vfs_find
bfb0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
bfc0: 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69   searches the li
bfd0: 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65  st.  Neither the
bfe0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
bff0: 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a  e nor the VFS.**
c000: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
c010: 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70  should use the p
c020: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  Next pointer..**
c030: 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69  .** The pNext fi
c040: 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20  eld is the only 
c050: 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c  field in the sql
c060: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75  ite3_vfs.** stru
c070: 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74  cture that SQLit
c080: 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69  e will ever modi
c090: 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  fy.  SQLite will
c0a0: 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20   only access.** 
c0b0: 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66  or modify this f
c0c0: 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69  ield while holdi
c0d0: 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  ng a particular 
c0e0: 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a  static mutex..**
c0f0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
c100: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f   should never mo
c110: 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69  dify anything wi
c120: 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  thin the sqlite3
c130: 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f  _vfs.** object o
c140: 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68  nce the object h
c150: 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72  as been register
c160: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e  ed..**.** The zN
c170: 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20  ame field holds 
c180: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
c190: 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65  VFS module.  The
c1a0: 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65   name must.** be
c1b0: 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61   unique across a
c1c0: 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a  ll VFS modules..
c1d0: 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f  **.** [[sqlite3_
c1e0: 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e  vfs.xOpen]].** ^
c1f0: 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
c200: 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65  s that the zFile
c210: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74  name parameter t
c220: 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69  o xOpen.** is ei
c230: 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ther a NULL poin
c240: 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62  ter or string ob
c250: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78  tained.** from x
c260: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77  FullPathname() w
c270: 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20  ith an optional 
c280: 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a  suffix added..**
c290: 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73   ^If a suffix is
c2a0: 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46   added to the zF
c2b0: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
c2c0: 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f  r, it will.** co
c2d0: 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c  nsist of a singl
c2e0: 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20  e "-" character 
c2f0: 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d  followed by no m
c300: 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61  ore than.** 11 a
c310: 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f  lphanumeric and/
c320: 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72  or "-" character
c330: 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75  s..** ^SQLite fu
c340: 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73  rther guarantees
c350: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72   that.** the str
c360: 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ing will be vali
c370: 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20  d and unchanged 
c380: 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69  until xClose() i
c390: 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63  s.** called. Bec
c3a0: 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76  ause of the prev
c3b0: 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a  ious sentence,.*
c3c0: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  * the [sqlite3_f
c3d0: 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20  ile] can safely 
c3e0: 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20  store a pointer 
c3f0: 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61  to the.** filena
c400: 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74  me if it needs t
c410: 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66  o remember the f
c420: 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65  ilename for some
c430: 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74   reason..** If t
c440: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
c450: 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20  ameter to xOpen 
c460: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
c470: 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20  r then xOpen.** 
c480: 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20  must invent its 
c490: 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61  own temporary na
c4a0: 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e  me for the file.
c4b0: 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20    ^Whenever the 
c4c0: 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61  .** xFilename pa
c4d0: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20  rameter is NULL 
c4e0: 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20  it will also be 
c4f0: 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
c500: 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d  e.** flags param
c510: 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64  eter will includ
c520: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
c530: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a  ELETEONCLOSE]..*
c540: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
c550: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
c560: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
c570: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74  bits set in.** t
c580: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
c590: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
c5a0: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66  en_v2()].  Or if
c5b0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
c5c0: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
c5d0: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73  _open16()] is us
c5e0: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69  ed, then flags i
c5f0: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74  ncludes at least
c600: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
c610: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
c620: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
c630: 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e  E]. .** If xOpen
c640: 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20  () opens a file 
c650: 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69  read-only then i
c660: 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67  t sets *pOutFlag
c670: 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  s to.** include 
c680: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
c690: 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62  DONLY].  Other b
c6a0: 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67  its in *pOutFlag
c6b0: 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a  s may be set..**
c6c0: 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c  .** ^(SQLite wil
c6d0: 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  l also add one o
c6e0: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
c6f0: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
c700: 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65  en().** call, de
c710: 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f  pending on the o
c720: 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e  bject being open
c730: 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ed:.**.** <ul>.*
c740: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
c750: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a  OPEN_MAIN_DB].**
c760: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
c770: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
c780: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
c790: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d  TE_OPEN_TEMP_DB]
c7a0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
c7b0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
c7c0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
c7d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
c7e0: 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  IENT_DB].** <li>
c7f0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53    [SQLITE_OPEN_S
c800: 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  UBJOURNAL].** <l
c810: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
c820: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d  _MASTER_JOURNAL]
c830: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
c840: 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c  E_OPEN_WAL].** <
c850: 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  /ul>)^.**.** The
c860: 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d   file I/O implem
c870: 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65  entation can use
c880: 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65   the object type
c890: 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61   flags to.** cha
c8a0: 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64  nge the way it d
c8b0: 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e  eals with files.
c8c0: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61    For example, a
c8d0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  n application.**
c8e0: 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63   that does not c
c8f0: 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20  are about crash 
c900: 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c  recovery or roll
c910: 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a  back might make.
c920: 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61  ** the open of a
c930: 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20   journal file a 
c940: 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74  no-op.  Writes t
c950: 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77  o this journal w
c960: 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20  ould.** also be 
c970: 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20  no-ops, and any 
c980: 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20  attempt to read 
c990: 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  the journal woul
c9a0: 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49  d return.** SQLI
c9b0: 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68  TE_IOERR.  Or th
c9c0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
c9d0: 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65   might recognize
c9e0: 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65   that a database
c9f0: 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  .** file will be
ca00: 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67   doing page-alig
ca10: 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73  ned sector reads
ca20: 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61   and writes in a
ca30: 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72   random.** order
ca40: 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20   and set up its 
ca50: 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63  I/O subsystem ac
ca60: 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a  cordingly..**.**
ca70: 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c   SQLite might al
ca80: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
ca90: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
caa0: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d  s to the xOpen m
cab0: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
cac0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
cad0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
cae0: 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  LOSE].** <li> [S
caf0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
cb00: 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  SIVE].** </ul>.*
cb10: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
cb20: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
cb30: 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20  OSE] flag means 
cb40: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
cb50: 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68  be.** deleted wh
cb60: 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e  en it is closed.
cb70: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f    ^The [SQLITE_O
cb80: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
cb90: 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65  E].** will be se
cba0: 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62  t for TEMP datab
cbb0: 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a  ases and their j
cbc0: 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65  ournals, transie
cbd0: 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c  nt.** databases,
cbe0: 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73   and subjournals
cbf0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ..**.** ^The [SQ
cc00: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
cc10: 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77  IVE] flag is alw
cc20: 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a  ays used in conj
cc30: 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20  unction.** with 
cc40: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
cc50: 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77  _CREATE] flag, w
cc60: 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69  hich are both di
cc70: 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67  rectly.** analog
cc80: 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43  ous to the O_EXC
cc90: 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c  L and O_CREAT fl
cca0: 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58  ags of the POSIX
ccb0: 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20   open().** API. 
ccc0: 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   The SQLITE_OPEN
ccd0: 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c  _EXCLUSIVE flag,
cce0: 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74   when paired wit
ccf0: 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45  h the .** SQLITE
cd00: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73  _OPEN_CREATE, is
cd10: 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74   used to indicat
cd20: 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75  e that file shou
cd30: 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ld always.** be 
cd40: 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61  created, and tha
cd50: 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72  t it is an error
cd60: 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65   if it already e
cd70: 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20  xists..** It is 
cd80: 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20  <i>not</i> used 
cd90: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20  to indicate the 
cda0: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f  file should be o
cdb0: 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78  pened .** for ex
cdc0: 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a  clusive access..
cdd0: 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20  **.** ^At least 
cde0: 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f  szOsFile bytes o
cdf0: 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c  f memory are all
ce00: 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65  ocated by SQLite
ce10: 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  .** to hold the 
ce20: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
ce30: 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64  structure passed
ce40: 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   as the third.**
ce50: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
ce60: 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d  en.  The xOpen m
ce70: 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68  ethod does not h
ce80: 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61  ave to.** alloca
ce90: 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65  te the structure
cea0: 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74  ; it should just
ceb0: 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f   fill it in.  No
cec0: 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78  te that.** the x
ced0: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74  Open method must
cee0: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33   set the sqlite3
cef0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74  _file.pMethods t
cf00: 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61  o either.** a va
cf10: 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  lid [sqlite3_io_
cf20: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
cf30: 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70  or to NULL.  xOp
cf40: 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68  en must do.** th
cf50: 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  is even if the o
cf60: 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69  pen fails.  SQLi
cf70: 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20  te expects that 
cf80: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
cf90: 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65  .pMethods.** ele
cfa0: 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c  ment will be val
cfb0: 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72  id after xOpen r
cfc0: 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73  eturns regardles
cfd0: 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73  s of the success
cfe0: 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f  .** or failure o
cff0: 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c  f the xOpen call
d000: 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65  ..**.** [[sqlite
d010: 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a  3_vfs.xAccess]].
d020: 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72  ** ^The flags ar
d030: 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73  gument to xAcces
d040: 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49  s() may be [SQLI
d050: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
d060: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72  ].** to test for
d070: 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f   the existence o
d080: 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51  f a file, or [SQ
d090: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
d0a0: 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73  WRITE] to.** tes
d0b0: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65  t whether a file
d0c0: 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64   is readable and
d0d0: 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53   writable, or [S
d0e0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
d0f0: 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68  D].** to test wh
d100: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
d110: 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c  at least readabl
d120: 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61  e.   The file ca
d130: 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74  n be a.** direct
d140: 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ory..**.** ^SQLi
d150: 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61  te will always a
d160: 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74  llocate at least
d170: 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79   mxPathname+1 by
d180: 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f  tes for the.** o
d190: 75 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75  utput buffer xFu
d1a0: 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65  llPathname.  The
d1b0: 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74   exact size of t
d1c0: 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  he output buffer
d1d0: 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73  .** is also pass
d1e0: 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65  ed as a paramete
d1f0: 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f  r to both  metho
d200: 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75  ds. If the outpu
d210: 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e  t buffer.** is n
d220: 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c  ot large enough,
d230: 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   [SQLITE_CANTOPE
d240: 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  N] should be ret
d250: 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69  urned. Since thi
d260: 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20  s is.** handled 
d270: 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72  as a fatal error
d280: 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20   by SQLite, vfs 
d290: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
d2a0: 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a  should endeavor.
d2b0: 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68  ** to prevent th
d2c0: 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78  is by setting mx
d2d0: 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75  Pathname to a su
d2e0: 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65  fficiently large
d2f0: 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68   value..**.** Th
d300: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c  e xRandomness(),
d310: 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72   xSleep(), xCurr
d320: 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78  entTime(), and x
d330: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
d340: 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  ().** interfaces
d350: 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c   are not strictl
d360: 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20  y a part of the 
d370: 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20  filesystem, but 
d380: 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c  they are.** incl
d390: 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20  uded in the VFS 
d3a0: 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f  structure for co
d3b0: 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54  mpleteness..** T
d3c0: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
d3d0: 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70   function attemp
d3e0: 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79  ts to return nBy
d3f0: 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  tes bytes.** of 
d400: 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e  good-quality ran
d410: 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75  domness into zOu
d420: 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76  t.  The return v
d430: 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61  alue is.** the a
d440: 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  ctual number of 
d450: 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e  bytes of randomn
d460: 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a  ess obtained..**
d470: 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65   The xSleep() me
d480: 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20  thod causes the 
d490: 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74  calling thread t
d4a0: 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a  o sleep for at.*
d4b0: 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62  * least the numb
d4c0: 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e  er of microsecon
d4d0: 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20  ds given.  ^The 
d4e0: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a  xCurrentTime().*
d4f0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
d500: 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75   a Julian Day Nu
d510: 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72  mber for the cur
d520: 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69  rent date and ti
d530: 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74  me as.** a float
d540: 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e  ing point value.
d550: 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e  .** ^The xCurren
d560: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74  tTimeInt64() met
d570: 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20  hod returns, as 
d580: 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20  an integer, the 
d590: 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75  Julian.** Day Nu
d5a0: 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20  mber multiplied 
d5b0: 62 79 20 38 36 34 30 30 30 30 30 20 28 74 68 65  by 86400000 (the
d5c0: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69   number of milli
d5d0: 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61  seconds in .** a
d5e0: 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20   24-hour day).  
d5f0: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
d600: 20 75 73 65 20 74 68 65 20 78 43 75 72 72 65 6e   use the xCurren
d610: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74  tTimeInt64() met
d620: 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 63  hod to get the c
d630: 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61  urrent.** date a
d640: 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 20  nd time if that 
d650: 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61  method is availa
d660: 62 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e  ble (if iVersion
d670: 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65   is 2 or .** gre
d680: 61 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e  ater and the fun
d690: 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
d6a0: 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77   not NULL) and w
d6b0: 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a  ill fall back.**
d6c0: 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65   to xCurrentTime
d6d0: 28 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 69  () if xCurrentTi
d6e0: 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61  meInt64() is una
d6f0: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  vailable..**.** 
d700: 5e 54 68 65 20 78 53 65 74 53 79 73 74 65 6d 43  ^The xSetSystemC
d710: 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65  all(), xGetSyste
d720: 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65  mCall(), and xNe
d730: 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69  stSystemCall() i
d740: 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65  nterfaces.** are
d750: 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68 65   not used by the
d760: 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54   SQLite core.  T
d770: 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e  hese optional in
d780: 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f  terfaces are pro
d790: 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65  vided.** by some
d7a0: 20 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69   VFSes to facili
d7b0: 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20  tate testing of 
d7c0: 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79  the VFS code. By
d7d0: 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20   overriding .** 
d7e0: 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74  system calls wit
d7f0: 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65  h functions unde
d800: 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61  r its control, a
d810: 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61   test program ca
d820: 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61  n.** simulate fa
d830: 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63  ults and error c
d840: 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77  onditions that w
d850: 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62  ould otherwise b
d860: 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f  e difficult.** o
d870: 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20  r impossible to 
d880: 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65 74  induce.  The set
d890: 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73   of system calls
d8a0: 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65   that can be ove
d8b0: 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65  rridden.** varie
d8c0: 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74  s from one VFS t
d8d0: 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66  o another, and f
d8e0: 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20  rom one version 
d8f0: 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46 53 20  of the same VFS 
d900: 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20  to the.** next. 
d910: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
d920: 61 74 20 75 73 65 20 74 68 65 73 65 20 69 6e 74  at use these int
d930: 65 72 66 61 63 65 73 20 6d 75 73 74 20 62 65 20  erfaces must be 
d940: 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79  prepared for any
d950: 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68  .** or all of th
d960: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 74  ese interfaces t
d970: 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72  o be NULL or for
d980: 20 74 68 65 69 72 20 62 65 68 61 76 69 6f 72 20   their behavior 
d990: 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f  to change.** fro
d9a0: 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f  m one release to
d9b0: 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c   the next.  Appl
d9c0: 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f  ications must no
d9d0: 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63  t attempt to acc
d9e0: 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68  ess.** any of th
d9f0: 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74  ese methods if t
da00: 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74  he iVersion of t
da10: 68 65 20 56 46 53 20 69 73 20 6c 65 73 73 20 74  he VFS is less t
da20: 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65  han 3..*/.typede
da30: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
da40: 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73  _vfs sqlite3_vfs
da50: 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28  ;.typedef void (
da60: 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c  *sqlite3_syscall
da70: 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72  _ptr)(void);.str
da80: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
da90: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
daa0: 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ;            /* 
dab0: 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f  Structure versio
dac0: 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e  n number (curren
dad0: 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20  tly 3) */.  int 
dae0: 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20  szOsFile;       
daf0: 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20       /* Size of 
db00: 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74  subclassed sqlit
db10: 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74  e3_file */.  int
db20: 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20   mxPathname;    
db30: 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
db40: 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c   file pathname l
db50: 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74  ength */.  sqlit
db60: 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20  e3_vfs *pNext;  
db70: 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69      /* Next regi
db80: 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20  stered VFS */.  
db90: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
dba0: 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  e;       /* Name
dbb0: 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c   of this virtual
dbc0: 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a   file system */.
dbd0: 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
dbe0: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f  ;          /* Po
dbf0: 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61  inter to applica
dc00: 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61  tion-specific da
dc10: 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f  ta */.  int (*xO
dc20: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
dc30: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
dc40: 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69  Name, sqlite3_fi
dc50: 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20  le*,.           
dc60: 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69      int flags, i
dc70: 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a  nt *pOutFlags);.
dc80: 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29    int (*xDelete)
dc90: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
dca0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
dcb0: 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a  , int syncDir);.
dcc0: 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29    int (*xAccess)
dcd0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
dce0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
dcf0: 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74  , int flags, int
dd00: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
dd10: 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d  t (*xFullPathnam
dd20: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
dd30: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
dd40: 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68  me, int nOut, ch
dd50: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69  ar *zOut);.  voi
dd60: 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71  d *(*xDlOpen)(sq
dd70: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
dd80: 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d  t char *zFilenam
dd90: 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c  e);.  void (*xDl
dda0: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
ddb0: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
ddc0: 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a  char *zErrMsg);.
ddd0: 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79    void (*(*xDlSy
dde0: 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  m)(sqlite3_vfs*,
ddf0: 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61  void*, const cha
de00: 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69  r *zSymbol))(voi
de10: 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c  d);.  void (*xDl
de20: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76  Close)(sqlite3_v
de30: 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69  fs*, void*);.  i
de40: 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73  nt (*xRandomness
de50: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
de60: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
de70: 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  *zOut);.  int (*
de80: 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f  xSleep)(sqlite3_
de90: 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73  vfs*, int micros
dea0: 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28  econds);.  int (
deb0: 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73  *xCurrentTime)(s
dec0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75  qlite3_vfs*, dou
ded0: 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ble*);.  int (*x
dee0: 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71  GetLastError)(sq
def0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c  lite3_vfs*, int,
df00: 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20   char *);.  /*. 
df10: 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20   ** The methods 
df20: 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72  above are in ver
df30: 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71  sion 1 of the sq
df40: 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a  lite_vfs object.
df50: 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e    ** definition.
df60: 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c    Those that fol
df70: 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e  low are added in
df80: 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61   version 2 or la
df90: 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28  ter.  */.  int (
dfa0: 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74  *xCurrentTimeInt
dfb0: 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  64)(sqlite3_vfs*
dfc0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a  , sqlite3_int64*
dfd0: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
dfe0: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
dff0: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31  re in versions 1
e000: 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71   and 2 of the sq
e010: 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e  lite_vfs object.
e020: 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f  .  ** Those belo
e030: 77 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f  w are for versio
e040: 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e  n 3 and greater.
e050: 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53  .  */.  int (*xS
e060: 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  etSystemCall)(sq
e070: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
e080: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73  t char *zName, s
e090: 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70  qlite3_syscall_p
e0a0: 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73  tr);.  sqlite3_s
e0b0: 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65  yscall_ptr (*xGe
e0c0: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
e0d0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
e0e0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20   char *zName);. 
e0f0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78   const char *(*x
e100: 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  NextSystemCall)(
e110: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
e120: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
e130: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
e140: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
e150: 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20  e in versions 1 
e160: 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65  through 3 of the
e170: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
e180: 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65  ct..  ** New fie
e190: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e  lds may be appen
e1a0: 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65  ded in figure ve
e1b0: 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65  rsions.  The iVe
e1c0: 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65  rsion.  ** value
e1d0: 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20   will increment 
e1e0: 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61  whenever this ha
e1f0: 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a  ppens. .  */.};.
e200: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
e210: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
e220: 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f  Access VFS metho
e230: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
e240: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
e250: 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74  can be used as t
e260: 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
e270: 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63  er to.** the xAc
e280: 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61  cess method of a
e290: 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  n [sqlite3_vfs] 
e2a0: 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65  object.  They de
e2b0: 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20  termine.** what 
e2c0: 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69  kind of permissi
e2d0: 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20  ons the xAccess 
e2e0: 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e  method is lookin
e2f0: 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53  g for..** With S
e300: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
e310: 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73  STS, the xAccess
e320: 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c   method.** simpl
e330: 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  y checks whether
e340: 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73   the file exists
e350: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
e360: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
e370: 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  E, the xAccess m
e380: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
e390: 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65  whether the name
e3a0: 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62  d directory is b
e3b0: 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64  oth readable and
e3c0: 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e   writable.** (in
e3d0: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66   other words, if
e3e0: 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64   files can be ad
e3f0: 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e  ded, removed, an
e400: 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e  d renamed within
e410: 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72  .** the director
e420: 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  y)..** The SQLIT
e430: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
e440: 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63  TE constant is c
e450: 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e  urrently used on
e460: 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65  ly by the.** [te
e470: 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
e480: 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75  ry pragma], thou
e490: 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68  gh this could ch
e4a0: 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65  ange in a future
e4b0: 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53  .** release of S
e4c0: 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53  QLite..** With S
e4d0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
e4e0: 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  D, the xAccess m
e4f0: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
e500: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
e510: 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54   is readable.  T
e520: 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  he SQLITE_ACCESS
e530: 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69  _READ constant i
e540: 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75  s.** currently u
e550: 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74  nused, though it
e560: 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69   might be used i
e570: 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61  n a future relea
e580: 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e  se of.** SQLite.
e590: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
e5a0: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
e5b0: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
e5c0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
e5d0: 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65  WRITE 1   /* Use
e5e0: 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70  d by PRAGMA temp
e5f0: 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
e600: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
e610: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20  TE_ACCESS_READ  
e620: 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65      2   /* Unuse
e630: 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d */../*.** CAPI
e640: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20  3REF: Flags for 
e650: 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53  the xShmLock VFS
e660: 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68   method.**.** Th
e670: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
e680: 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65  tants define the
e690: 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67   various locking
e6a0: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61   operations.** a
e6b0: 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53  llowed by the xS
e6c0: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66  hmLock method of
e6d0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
e6e0: 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66  hods].  The.** f
e6f0: 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65  ollowing are the
e700: 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62   only legal comb
e710: 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67  inations of flag
e720: 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d  s to the.** xShm
e730: 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a  Lock method:.**.
e740: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
e750: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
e760: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48   | SQLITE_SHM_SH
e770: 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  ARED.** <li>  SQ
e780: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20  LITE_SHM_LOCK | 
e790: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
e7a0: 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  SIVE.** <li>  SQ
e7b0: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
e7c0: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
e7d0: 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
e7e0: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
e7f0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
e800: 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  USIVE.** </ul>.*
e810: 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b  *.** When unlock
e820: 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48  ing, the same SH
e830: 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56  ARED or EXCLUSIV
e840: 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73  E flag must be s
e850: 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61  upplied as.** wa
e860: 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20 63  s given no the c
e870: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63  orresponding loc
e880: 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  k.  .**.** The x
e890: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63  ShmLock method c
e8a0: 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65  an transition be
e8b0: 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61  tween unlocked a
e8c0: 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20  nd SHARED or.** 
e8d0: 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64  between unlocked
e8e0: 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20   and EXCLUSIVE. 
e8f0: 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73   It cannot trans
e900: 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48  ition between SH
e910: 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c  ARED.** and EXCL
e920: 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e  USIVE..*/.#defin
e930: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c  e SQLITE_SHM_UNL
e940: 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66  OCK       1.#def
e950: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  ine SQLITE_SHM_L
e960: 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64  OCK         2.#d
e970: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
e980: 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a  _SHARED       4.
e990: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
e9a0: 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  HM_EXCLUSIVE    
e9b0: 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  8../*.** CAPI3RE
e9c0: 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c  F: Maximum xShmL
e9d0: 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20  ock index.**.** 
e9e0: 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  The xShmLock met
e9f0: 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f  hod on [sqlite3_
ea00: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20  io_methods] may 
ea10: 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65  use values.** be
ea20: 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73  tween 0 and this
ea30: 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20   upper bound as 
ea40: 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67  its "offset" arg
ea50: 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51  ument..** The SQ
ea60: 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e  Lite core will n
ea70: 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20  ever attempt to 
ea80: 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61  acquire or relea
ea90: 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74  se a.** lock out
eaa0: 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e  side of this ran
eab0: 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ge.*/.#define SQ
eac0: 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20  LITE_SHM_NLOCK  
ead0: 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20        8.../*.** 
eae0: 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61  CAPI3REF: Initia
eaf0: 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20  lize The SQLite 
eb00: 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54  Library.**.** ^T
eb10: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
eb20: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
eb30: 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a  initializes the.
eb40: 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  ** SQLite librar
eb50: 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  y.  ^The sqlite3
eb60: 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74  _shutdown() rout
eb70: 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74  ine.** deallocat
eb80: 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  es any resources
eb90: 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63   that were alloc
eba0: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
ebb0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a  initialize()..**
ebc0: 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
ebd0: 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20  are designed to 
ebe0: 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69  aid in process i
ebf0: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e  nitialization an
ec00: 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e  d.** shutdown on
ec10: 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d   embedded system
ec20: 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20  s.  Workstation 
ec30: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69  applications usi
ec40: 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72  ng.** SQLite nor
ec50: 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65  mally do not nee
ec60: 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68  d to invoke eith
ec70: 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  er of these rout
ec80: 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ines..**.** A ca
ec90: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
eca0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e  itialize() is an
ecb0: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
ecc0: 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68  l if it is.** th
ecd0: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
ece0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ecf0: 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72  ) is invoked dur
ed00: 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65  ing the lifetime
ed10: 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65   of.** the proce
ed20: 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20  ss, or if it is 
ed30: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
ed40: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
ed50: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
ed60: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61  * following a ca
ed70: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
ed80: 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c  utdown().  ^(Onl
ed90: 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  y an effective c
eda0: 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  all.** of sqlite
edb0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
edc0: 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69  oes any initiali
edd0: 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68  zation.  All oth
ede0: 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20  er calls.** are 
edf0: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
ee00: 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  )^.**.** A call 
ee10: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
ee20: 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66  own() is an "eff
ee30: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
ee40: 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  it is the first.
ee50: 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ** call to sqlit
ee60: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69  e3_shutdown() si
ee70: 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c  nce the last sql
ee80: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ee90: 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e  ).  ^(Only.** an
eea0: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20   effective call 
eeb0: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
eec0: 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64  own() does any d
eed0: 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e  einitialization.
eee0: 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  .** All other va
eef0: 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  lid calls to sql
ef00: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
ef10: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
ef20: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ops.)^.**.** The
ef30: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
ef40: 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ize() interface 
ef50: 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62  is threadsafe, b
ef60: 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  ut sqlite3_shutd
ef70: 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e  own().** is not.
ef80: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68    The sqlite3_sh
ef90: 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61  utdown() interfa
efa0: 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20  ce must only be 
efb0: 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  called from a.**
efc0: 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20   single thread. 
efd0: 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62   All open [datab
efe0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
eff0: 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20   must be closed 
f000: 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72  and all.** other
f010: 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65   SQLite resource
f020: 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f  s must be deallo
f030: 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69  cated prior to i
f040: 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  nvoking.** sqlit
f050: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a  e3_shutdown()..*
f060: 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72  *.** Among other
f070: 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65   things, ^sqlite
f080: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77  3_initialize() w
f090: 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  ill invoke.** sq
f0a0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
f0b0: 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71    Similarly, ^sq
f0c0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f0d0: 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  .** will invoke 
f0e0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
f0f0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
f100: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f110: 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
f120: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  s [SQLITE_OK] on
f130: 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66   success..** ^If
f140: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
f150: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  , sqlite3_initia
f160: 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65  lize() is unable
f170: 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a   to initialize.*
f180: 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70  * the library (p
f190: 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61  erhaps it is una
f1a0: 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
f1b0: 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63  a needed resourc
f1c0: 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d  e such.** as a m
f1d0: 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73  utex) it returns
f1e0: 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
f1f0: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
f200: 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
f210: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
f220: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
f230: 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72   is called inter
f240: 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74  nally by many ot
f250: 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
f260: 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74  terfaces so that
f270: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
f280: 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74  usually does not
f290: 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f   need to.** invo
f2a0: 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ke sqlite3_initi
f2b0: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
f2c0: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
f2d0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
f2e0: 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65  .** calls sqlite
f2f0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73  3_initialize() s
f300: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  o the SQLite lib
f310: 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74  rary will be aut
f320: 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e  omatically.** in
f330: 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b  itialized when [
f340: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
f350: 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20  is called if it 
f360: 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69  has not be initi
f370: 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64  alized.** alread
f380: 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66  y.  ^However, if
f390: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
f3a0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51  led with the [SQ
f3b0: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
f3c0: 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  IT].** compile-t
f3d0: 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  ime option, then
f3e0: 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63   the automatic c
f3f0: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
f400: 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
f410: 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20  are omitted and 
f420: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
f430: 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65  must call sqlite
f440: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
f450: 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72  irectly.** prior
f460: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
f470: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
f480: 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d  face.  For maxim
f490: 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a  um portability,.
f4a0: 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** it is recomme
f4b0: 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
f4c0: 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e  ations always in
f4d0: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
f4e0: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72  tialize().** dir
f4f0: 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75  ectly prior to u
f500: 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
f510: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
f520: 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65    Future release
f530: 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d  s.** of SQLite m
f540: 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e  ay require this.
f550: 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
f560: 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65  , the behavior e
f570: 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e  xhibited.** when
f580: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
f590: 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  led with [SQLITE
f5a0: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20  _OMIT_AUTOINIT] 
f5b0: 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65  might become the
f5c0: 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61  .** default beha
f5d0: 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74  vior in some fut
f5e0: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  ure release of S
f5f0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
f600: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
f610: 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
f620: 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
f630: 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69   specific.** ini
f640: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74  tialization of t
f650: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
f660: 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  y.  The sqlite3_
f670: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74  os_end().** rout
f680: 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65  ine undoes the e
f690: 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33  ffect of sqlite3
f6a0: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70  _os_init().  Typ
f6b0: 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65  ical tasks.** pe
f6c0: 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65  rformed by these
f6d0: 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64   routines includ
f6e0: 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20  e allocation or 
f6f0: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  deallocation.** 
f700: 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72  of static resour
f710: 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74  ces, initializat
f720: 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61  ion of global va
f730: 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74  riables,.** sett
f740: 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74  ing up a default
f750: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d   [sqlite3_vfs] m
f760: 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e  odule, or settin
f770: 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c  g up.** a defaul
f780: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  t configuration 
f790: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
f7a0: 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  onfig()]..**.** 
f7b0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
f7c0: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76  should never inv
f7d0: 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74  oke either sqlit
f7e0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
f7f0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
f800: 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54  d() directly.  T
f810: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
f820: 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b  hould only invok
f830: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69  e.** sqlite3_ini
f840: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71  tialize() and sq
f850: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f860: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
f870: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65  s_init().** inte
f880: 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20  rface is called 
f890: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
f8a0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f8b0: 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c  ize() and.** sql
f8c0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73  ite3_os_end() is
f8d0: 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74   called by sqlit
f8e0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
f8f0: 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69  Appropriate.** i
f900: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66  mplementations f
f910: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  or sqlite3_os_in
f920: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
f930: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65  _os_end().** are
f940: 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
f950: 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f  te when it is co
f960: 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c  mpiled for Unix,
f970: 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f   Windows, or OS/
f980: 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74  2..** When [cust
f990: 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c  om builds | buil
f9a0: 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74  t for other plat
f9b0: 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67  forms].** (using
f9c0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f   the [SQLITE_OS_
f9d0: 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65  OTHER=1] compile
f9e0: 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29  -time.** option)
f9f0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
fa00: 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73   must supply a s
fa10: 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  uitable implemen
fa20: 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71  tation for.** sq
fa30: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
fa40: 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
fa50: 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63  nd().  An applic
fa60: 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a  ation-supplied.*
fa70: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
fa80: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
fa90: 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  nit() or sqlite3
faa0: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73  _os_end().** mus
fab0: 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  t return [SQLITE
fac0: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
fad0: 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b  and some other [
fae0: 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e  error code] upon
faf0: 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a  .** failure..*/.
fb00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  int sqlite3_init
fb10: 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e  ialize(void);.in
fb20: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
fb30: 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  wn(void);.int sq
fb40: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f  lite3_os_init(vo
fb50: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
fb60: 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a  _os_end(void);..
fb70: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
fb80: 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20  Configuring The 
fb90: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a  SQLite Library.*
fba0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
fbb0: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
fbc0: 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d  ace is used to m
fbd0: 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69  ake global confi
fbe0: 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
fbf0: 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e  ges to SQLite in
fc00: 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53   order to tune S
fc10: 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65  QLite to the spe
fc20: 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a  cific needs of.*
fc30: 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
fc40: 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  n.  The default 
fc50: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73  configuration is
fc60: 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
fc70: 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61   most.** applica
fc80: 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69  tions and so thi
fc90: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75  s routine is usu
fca0: 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61  ally not necessa
fcb0: 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72  ry.  It is.** pr
fcc0: 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72  ovided to suppor
fcd0: 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69  t rare applicati
fce0: 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c  ons with unusual
fcf0: 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68   needs..**.** Th
fd00: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
fd10: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
fd20: 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20  not threadsafe. 
fd30: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
fd40: 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20  .** must insure 
fd50: 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51  that no other SQ
fd60: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
fd70: 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f  are invoked by o
fd80: 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20  ther.** threads 
fd90: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  while sqlite3_co
fda0: 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e  nfig() is runnin
fdb0: 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c  g.  Furthermore,
fdc0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
fdd0: 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ).** may only be
fde0: 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74   invoked prior t
fdf0: 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61  o library initia
fe00: 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  lization using.*
fe10: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  * [sqlite3_initi
fe20: 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
fe30: 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73  r shutdown by [s
fe40: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fe50: 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  )]..** ^If sqlit
fe60: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63  e3_config() is c
fe70: 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
fe80: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
fe90: 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a  )] and before.**
fea0: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
feb0: 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69  wn()] then it wi
fec0: 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ll return SQLITE
fed0: 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65  _MISUSE..** Note
fee0: 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20  , however, that 
fef0: 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  ^sqlite3_config(
ff00: 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  ) can be called 
ff10: 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a  as part of the.*
ff20: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
ff30: 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   of an applicati
ff40: 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69  on-defined [sqli
ff50: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a  te3_os_init()]..
ff60: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
ff70: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
ff80: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
ff90: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63  an integer.** [c
ffa0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
ffb0: 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d  ion] that determ
ffc0: 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f  ines.** what pro
ffd0: 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20  perty of SQLite 
ffe0: 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75  is to be configu
fff0: 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74  red.  Subsequent
10000 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61   arguments.** va
10010 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
10020 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69  the [configurati
10030 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e  on option].** in
10040 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
10050 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  ent..**.** ^When
10060 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   a configuration
10070 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20   option is set, 
10080 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10090 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
100a0 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  _OK]..** ^If the
100b0 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f   option is unkno
100c0 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20  wn or SQLite is 
100d0 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68  unable to set th
100e0 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e  e option.** then
100f0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
10100 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f  turns a non-zero
10110 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
10120 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
10130 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a  nfig(int, ...);.
10140 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10150 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62   Configure datab
10160 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a  ase connections.
10170 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
10180 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e  3_db_config() in
10190 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
101a0 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72  to make configur
101b0 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
101c0 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20   to a [database 
101d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68  connection].  Th
101e0 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73  e interface is s
101f0 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71  imilar to.** [sq
10200 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
10210 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20  except that the 
10220 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f  changes apply to
10230 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61   a single.** [da
10240 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10250 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e  n] (specified in
10260 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
10270 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ent)..**.** The 
10280 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
10290 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  to sqlite3_db_co
102a0 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69  nfig(D,V,...)  i
102b0 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
102c0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
102d0 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74  IDE | configurat
102e0 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69  ion verb] - an i
102f0 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20  nteger code .** 
10300 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77  that indicates w
10310 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 68  hat aspect of th
10320 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
10330 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67  ection] is being
10340 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20   configured..** 
10350 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
10360 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e 64  ents vary depend
10370 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69  ing on the confi
10380 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a  guration verb..*
10390 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73  *.** ^Calls to s
103a0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
103b0 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  () return SQLITE
103c0 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  _OK if and only 
103d0 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69  if.** the call i
103e0 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63  s considered suc
103f0 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  cessful..*/.int 
10400 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
10410 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  g(sqlite3*, int 
10420 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  op, ...);../*.**
10430 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
10440 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75  y Allocation Rou
10450 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  tines.**.** An i
10460 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
10470 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
10480 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
10490 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61  ween SQLite.** a
104a0 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  nd low-level mem
104b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
104c0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
104d0 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73  his object is us
104e0 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70  ed in only one p
104f0 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69  lace in the SQLi
10500 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
10510 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   A pointer to an
10520 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
10530 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20  s object is the 
10540 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b  argument to.** [
10550 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10560 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69  ] when the confi
10570 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
10580 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  is.** [SQLITE_CO
10590 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20  NFIG_MALLOC] or 
105a0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
105b0 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20  ETMALLOC].  .** 
105c0 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69  By creating an i
105d0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
105e0 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61  object.** and pa
105f0 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
10600 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
10610 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
10620 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63  OC]).** during c
10630 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e  onfiguration, an
10640 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e   application can
10650 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
10660 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
10670 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
10680 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74  system for SQLit
10690 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c  e to use for all
106a0 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d   of its.** dynam
106b0 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e  ic memory needs.
106c0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
106d0 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69   SQLite comes wi
106e0 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c  th several [buil
106f0 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
10700 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20  cators].** that 
10710 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 64  are perfectly ad
10720 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f  equate for the o
10730 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f  verwhelming majo
10740 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
10750 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74  ions.** and that
10760 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
10770 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61  only useful to a
10780 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f   tiny minority o
10790 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
107a0 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a  * with specializ
107b0 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
107c0 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74  tion requirement
107d0 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  s.  This object 
107e0 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20  is.** also used 
107f0 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f  during testing o
10800 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  f SQLite in orde
10810 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20  r to specify an 
10820 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
10830 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
10840 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d  that simulates m
10850 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d  emory out-of-mem
10860 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69  ory conditions i
10870 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65  n.** order to ve
10880 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65  rify that SQLite
10890 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66   recovers gracef
108a0 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a  ully from such.*
108b0 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a  * conditions..**
108c0 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c  .** The xMalloc,
108d0 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78   xRealloc, and x
108e0 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73  Free methods mus
108f0 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a  t work like the.
10900 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61  ** malloc(), rea
10910 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
10920 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d  ) functions from
10930 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
10940 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c  library..** ^SQL
10950 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74  ite guarantees t
10960 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61  hat the second a
10970 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52  rgument to.** xR
10980 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73  ealloc is always
10990 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65   a value returne
109a0 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c  d by a prior cal
109b0 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a  l to xRoundup..*
109c0 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c  *.** xSize shoul
109d0 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c  d return the all
109e0 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61  ocated size of a
109f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
10a00 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  on.** previously
10a10 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78   obtained from x
10a20 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c  Malloc or xReall
10a30 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74  oc.  The allocat
10a40 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c  ed size.** is al
10a50 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73  ways at least as
10a60 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75   big as the requ
10a70 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d  ested size but m
10a80 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a  ay be larger..**
10a90 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70  .** The xRoundup
10aa0 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
10ab0 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68  what would be th
10ac0 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
10ad0 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20   of.** a memory 
10ae0 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e  allocation given
10af0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
10b00 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d  quested size.  M
10b10 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ost memory.** al
10b20 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
10b30 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  p memory allocat
10b40 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f  ions at least to
10b50 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70   the next multip
10b60 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d  le.** of 8.  Som
10b70 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  e allocators rou
10b80 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65  nd up to a large
10b90 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f  r multiple or to
10ba0 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a   a power of 2..*
10bb0 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61  * Every memory a
10bc0 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73  llocation reques
10bd0 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f  t coming in thro
10be0 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ugh [sqlite3_mal
10bf0 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  loc()].** or [sq
10c00 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
10c10 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f   first calls xRo
10c20 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e  undup.  If xRoun
10c30 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a  dup returns 0, .
10c40 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74  ** that causes t
10c50 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
10c60 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
10c70 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a  on to fail..**.*
10c80 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68  * The xInit meth
10c90 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  od initializes t
10ca0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
10cb0 74 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  tor.  For exampl
10cc0 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61  e,.** it might a
10cd0 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75  llocate any requ
10ce0 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69  ire mutexes or i
10cf0 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e  nitialize intern
10d00 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63  al data.** struc
10d10 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75  tures.  The xShu
10d20 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
10d30 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63  invoked (indirec
10d40 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  tly) by.** [sqli
10d50 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
10d60 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c  and should deall
10d70 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72  ocate any resour
10d80 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20  ces acquired.** 
10d90 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70  by xInit.  The p
10da0 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20  AppData pointer 
10db0 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f  is used as the o
10dc0 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
10dd0 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53  .** xInit and xS
10de0 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53  hutdown..**.** S
10df0 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20  QLite holds the 
10e00 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
10e10 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74  ATIC_MASTER] mut
10e20 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b  ex when it invok
10e30 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20  es.** the xInit 
10e40 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78  method, so the x
10e50 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64  Init method need
10e60 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61   not be threadsa
10e70 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75  fe.  The.** xShu
10e80 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
10e90 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d  only called from
10ea0 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
10eb0 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73  wn()] so it does
10ec0 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  .** not need to 
10ed0 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69  be threadsafe ei
10ee0 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f  ther.  For all o
10ef0 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51  ther methods, SQ
10f00 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68  Lite.** holds th
10f10 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
10f20 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65  STATIC_MEM] mute
10f30 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  x as long as the
10f40 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
10f50 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f  IG_MEMSTATUS] co
10f60 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10f70 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20  on is turned on 
10f80 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20  (which.** it is 
10f90 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20  by default) and 
10fa0 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61  so the methods a
10fb0 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  re automatically
10fc0 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20   serialized..** 
10fd0 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c  However, if [SQL
10fe0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
10ff0 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65  ATUS] is disable
11000 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65  d, then the othe
11010 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73  r.** methods mus
11020 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  t be threadsafe 
11030 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65  or else make the
11040 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65  ir own arrangeme
11050 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61  nts for.** seria
11060 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  lization..**.** 
11070 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
11080 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29  r invoke xInit()
11090 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20   more than once 
110a0 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72  without an inter
110b0 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74  vening.** call t
110c0 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a  o xShutdown()..*
110d0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
110e0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
110f0 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d  hods sqlite3_mem
11100 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
11110 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
11120 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28  hods {.  void *(
11130 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20  *xMalloc)(int); 
11140 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72          /* Memor
11150 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e  y allocation fun
11160 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
11170 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b  (*xFree)(void*);
11180 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65            /* Fre
11190 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  e a prior alloca
111a0 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
111b0 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64  (*xRealloc)(void
111c0 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69  *,int);  /* Resi
111d0 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze an allocation
111e0 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a   */.  int (*xSiz
111f0 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
11200 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74       /* Return t
11210 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c  he size of an al
11220 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
11230 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e  t (*xRoundup)(in
11240 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  t);          /* 
11250 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74  Round up request
11260 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74   size to allocat
11270 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e  ion size */.  in
11280 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a  t (*xInit)(void*
11290 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
112a0 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  Initialize the m
112b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
112c0 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75  */.  void (*xShu
112d0 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20  tdown)(void*);  
112e0 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c      /* Deinitial
112f0 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
11300 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
11310 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
11320 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
11330 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69  Argument to xIni
11340 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77  t() and xShutdow
11350 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  n() */.};../*.**
11360 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
11370 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
11380 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
11390 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
113a0 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ion}.**.** These
113b0 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
113c0 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
113d0 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
113e0 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
113f0 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
11400 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
11410 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
11420 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
11430 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
11440 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
11450 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
11460 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
11470 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
11480 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
11490 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
114a0 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
114b0 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
114c0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
114d0 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
114e0 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
114f0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  om [sqlite3_conf
11500 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
11510 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
11520 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65  all worked.  The
11530 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
11540 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
11550 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
11560 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
11570 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
11580 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
11590 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
115a0 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
115b0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
115c0 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
115d0 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
115e0 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  READ]] <dt>SQLIT
115f0 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
11600 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
11610 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
11620 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
11630 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
11640 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
11650 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
11660 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68  de] to Single-th
11670 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
11680 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
11690 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69  es.** all mutexi
116a0 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69  ng and puts SQLi
116b0 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77  te into a mode w
116c0 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79  here it can only
116d0 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61   be used.** by a
116e0 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20   single thread. 
116f0 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
11700 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
11710 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
11720 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
11730 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
11740 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
11750 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
11760 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
11770 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72   change the [thr
11780 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f  eading mode] fro
11790 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a  m its default.**
117a0 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65   value of Single
117b0 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b  -thread and so [
117c0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
117d0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a  ] will return .*
117e0 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
117f0 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
11800 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
11810 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a  G_SINGLETHREAD.*
11820 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
11830 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
11840 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
11850 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d  IG_MULTITHREAD]]
11860 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
11870 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f  IG_MULTITHREAD</
11880 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
11890 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
118a0 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
118b0 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
118c0 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
118d0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
118e0 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49  Multi-thread.  I
118f0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
11900 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75  t disables.** mu
11910 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62  texing on [datab
11920 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
11930 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
11940 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
11950 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
11960 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69  tion is responsi
11970 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a  ble for serializ
11980 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a  ing access to.**
11990 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
119a0 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
119b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
119c0 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75  ].  But other mu
119d0 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61  texes.** are ena
119e0 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c  bled so that SQL
119f0 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65  ite will be safe
11a00 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c   to use in a mul
11a10 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65  ti-threaded.** e
11a20 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f  nvironment as lo
11a30 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72  ng as no two thr
11a40 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20  eads attempt to 
11a50 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  use the same.** 
11a60 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11a70 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d  tion] at the sam
11a80 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c  e time.  ^If SQL
11a90 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
11aa0 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
11ab0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
11ac0 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
11ad0 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
11ae0 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
11af0 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
11b00 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
11b10 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  Multi-thread [th
11b20 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
11b30 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
11b40 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
11b50 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
11b60 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
11b70 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
11b80 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
11b90 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  AD configuration
11ba0 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
11bb0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
11bc0 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d  FIG_SERIALIZED]]
11bd0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
11be0 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64  IG_SERIALIZED</d
11bf0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
11c00 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
11c10 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
11c20 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
11c30 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
11c40 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
11c50 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74  erialized. In ot
11c60 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20  her words, this 
11c70 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a  option enables.*
11c80 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e  * all mutexes in
11c90 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75  cluding the recu
11ca0 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73  rsive.** mutexes
11cb0 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
11cc0 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
11cd0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
11ce0 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49  t] objects..** I
11cf0 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69  n this mode (whi
11d00 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c  ch is the defaul
11d10 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  t when SQLite is
11d20 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
11d30 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
11d40 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c  SAFE=1]) the SQL
11d50 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
11d60 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a   itself serializ
11d70 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b  e access.** to [
11d80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11d90 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
11da0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
11db0 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61  so that the.** a
11dc0 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72  pplication is fr
11dd0 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  ee to use the sa
11de0 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
11df0 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a  nection] or the.
11e00 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  ** same [prepare
11e10 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
11e20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
11e30 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  s at the same ti
11e40 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74  me..** ^If SQLit
11e50 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
11e60 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
11e70 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
11e80 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
11e90 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
11ea0 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
11eb0 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
11ec0 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65  le to set the Se
11ed0 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
11ee0 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a  ing mode] and.**
11ef0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
11f00 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
11f10 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
11f20 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
11f30 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  e.** SQLITE_CONF
11f40 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f  IG_SERIALIZED co
11f50 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11f60 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
11f70 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
11f80 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
11f90 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
11fa0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
11fb0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
11fc0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
11fd0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
11fe0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
11ff0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
12000 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
12010 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
12020 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
12030 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
12040 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
12050 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
12060 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ion routines to 
12070 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
12080 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72   of.** the memor
12090 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
120a0 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
120b0 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69   SQLite.)^ ^SQLi
120c0 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20  te makes.** its 
120d0 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
120e0 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   of the content 
120f0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
12100 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
12110 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65  ucture.** before
12120 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
12130 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74  nfig()] call ret
12140 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  urns.</dd>.**.**
12150 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
12160 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  _GETMALLOC]] <dt
12170 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
12180 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  ETMALLOC</dt>.**
12190 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
121a0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
121b0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
121c0 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
121d0 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
121e0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
121f0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
12200 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73  ructure.  The [s
12210 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12220 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
12230 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
12240 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
12250 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  fined memory all
12260 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
12270 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  .)^.** This opti
12280 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
12290 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
122a0 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
122b0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
122c0 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
122d0 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  per that simulat
122e0 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ions memory allo
122f0 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f  cation failure o
12300 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f  r.** tracks memo
12310 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78  ry usage, for ex
12320 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ample. </dd>.**.
12330 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
12340 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c  IG_MEMSTATUS]] <
12350 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12360 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a  _MEMSTATUS</dt>.
12370 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
12380 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c  tion takes singl
12390 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
123a0 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65  pe int, interpre
123b0 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f  ted as a .** boo
123c0 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62  lean, which enab
123d0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
123e0 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  the collection o
123f0 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  f memory allocat
12400 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69  ion .** statisti
12410 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72  cs. ^(When memor
12420 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
12430 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61  tistics are disa
12440 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f  bled, the .** fo
12450 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69  llowing SQLite i
12460 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65  nterfaces become
12470 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c   non-operational
12480 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20  :.**   <ul>.**  
12490 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
124a0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a  emory_used()].**
124b0 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
124c0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
124d0 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  r()].**   <li> [
124e0 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
124f0 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20  p_limit64()].** 
12500 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
12510 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c  status()].**   <
12520 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72  /ul>)^.** ^Memor
12530 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
12540 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62  tistics are enab
12550 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75  led by default u
12560 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a  nless SQLite is.
12570 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
12580 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
12590 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e  _MEMSTATUS]=0 in
125a0 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f   which case memo
125b0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
125c0 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
125d0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
125e0 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ult..** </dd>.**
125f0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12600 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64  FIG_SCRATCH]] <d
12610 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12620 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20  SCRATCH</dt>.** 
12630 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
12640 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
12650 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
12660 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  er that SQLite c
12670 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63  an use for.** sc
12680 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54  ratch memory.  T
12690 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
126a0 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69  rguments:  A poi
126b0 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a  nter an 8-byte.*
126c0 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79  * aligned memory
126d0 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69   buffer from whi
126e0 63 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61  ch the scratch a
126f0 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20  llocations will 
12700 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65  be.** drawn, the
12710 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63   size of each sc
12720 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
12730 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68   (sz),.** and th
12740 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
12750 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f   of scratch allo
12760 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68  cations (N).  Th
12770 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  e sz.** argument
12780 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69   must be a multi
12790 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68  ple of 16..** Th
127a0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
127b0 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74   must be a point
127c0 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  er to an 8-byte 
127d0 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a  aligned buffer.*
127e0 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  * of at least sz
127f0 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
12800 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ry..** ^SQLite w
12810 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20  ill use no more 
12820 74 68 61 6e 20 74 77 6f 20 73 63 72 61 74 63 68  than two scratch
12830 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72   buffers per thr
12840 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68  ead.  So.** N sh
12850 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74  ould be set to t
12860 77 69 63 65 20 74 68 65 20 65 78 70 65 63 74 65  wice the expecte
12870 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  d maximum number
12880 20 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20   of threads..** 
12890 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76  ^SQLite will nev
128a0 65 72 20 72 65 71 75 69 72 65 20 61 20 73 63 72  er require a scr
128b0 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74  atch buffer that
128c0 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a   is more than 6.
128d0 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74  ** times the dat
128e0 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e  abase page size.
128f0 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64   ^If SQLite need
12900 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e  s needs addition
12910 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65  al.** scratch me
12920 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74  mory beyond what
12930 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
12940 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  this configurati
12950 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  on option, then 
12960 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
12970 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75  loc()] will be u
12980 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  sed to obtain th
12990 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e  e memory needed.
129a0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
129b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
129c0 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  CACHE]] <dt>SQLI
129d0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
129e0 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
129f0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70   ^This option sp
12a00 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
12a10 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
12a20 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
12a30 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61  se for.** the da
12a40 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68  tabase page cach
12a50 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75  e with the defau
12a60 6c 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  lt page cache im
12a70 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a  plementation.  .
12a80 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72  ** This configur
12a90 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74  ation should not
12aa0 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61   be used if an a
12ab0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
12ac0 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  e page.** cache 
12ad0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
12ae0 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74  s loaded using t
12af0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
12b00 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 2e  _PCACHE2 option.
12b10 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68  .** There are th
12b20 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ree arguments to
12b30 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20   this option: A 
12b40 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74  pointer to 8-byt
12b50 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d  e aligned.** mem
12b60 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66  ory, the size of
12b70 20 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65   each page buffe
12b80 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20  r (sz), and the 
12b90 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20  number of pages 
12ba0 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61  (N)..** The sz a
12bb0 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
12bc0 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  e the size of th
12bd0 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61  e largest databa
12be0 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f  se page.** (a po
12bf0 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65  wer of two betwe
12c00 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36 38  en 512 and 32768
12c10 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20  ) plus a little 
12c20 65 78 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a  extra for each.*
12c30 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20  * page header.  
12c40 5e 54 68 65 20 70 61 67 65 20 68 65 61 64 65 72  ^The page header
12c50 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34   size is 20 to 4
12c60 30 20 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e  0 bytes dependin
12c70 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74  g on.** the host
12c80 20 61 72 63 68 69 74 65 63 74 75 72 65 2e 20 20   architecture.  
12c90 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c  ^It is harmless,
12ca0 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20   apart from the 
12cb0 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a  wasted memory,.*
12cc0 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c  * to make sz a l
12cd0 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e  ittle too large.
12ce0 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61    The first.** a
12cf0 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70  rgument should p
12d00 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63  oint to an alloc
12d10 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73  ation of at leas
12d20 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
12d30 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  memory..** ^SQLi
12d40 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
12d50 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20  memory provided 
12d60 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67  by the first arg
12d70 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79  ument to satisfy
12d80 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e   its.** memory n
12d90 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72  eeds for the fir
12da0 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20  st N pages that 
12db0 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65  it adds to cache
12dc0 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61  .  ^If additiona
12dd0 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  l.** page cache 
12de0 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64  memory is needed
12df0 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
12e00 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
12e10 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a   option, then.**
12e20 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20   SQLite goes to 
12e30 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
12e40 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74  )] for the addit
12e50 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70  ional storage sp
12e60 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e  ace..** The poin
12e70 74 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74  ter in the first
12e80 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a   argument must.*
12e90 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  * be aligned to 
12ea0 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61  an 8-byte bounda
12eb0 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  ry or subsequent
12ec0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
12ed0 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75  ite.** will be u
12ee0 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a  ndefined.</dd>.*
12ef0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12f00 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e  NFIG_HEAP]] <dt>
12f10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
12f20 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  AP</dt>.** <dd> 
12f30 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
12f40 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
12f50 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
12f60 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  at SQLite will u
12f70 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66  se.** for all of
12f80 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d   its dynamic mem
12f90 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
12fa0 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73  eeds beyond thos
12fb0 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f  e provided.** fo
12fc0 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r by [SQLITE_CON
12fd0 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64  FIG_SCRATCH] and
12fe0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
12ff0 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54  PAGECACHE]..** T
13000 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
13010 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62  rguments: An 8-b
13020 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e  yte aligned poin
13030 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ter to the memor
13040 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  y,.** the number
13050 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
13060 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20   memory buffer, 
13070 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  and the minimum 
13080 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e  allocation size.
13090 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73  .** ^If the firs
130a0 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
130b0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69  emory pointer) i
130c0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c  s NULL, then SQL
130d0 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74  ite reverts.** t
130e0 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61  o using its defa
130f0 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
13100 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d  ator (the system
13110 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d   malloc() implem
13120 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e  entation),.** un
13130 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20  doing any prior 
13140 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53  invocation of [S
13150 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
13160 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a  LOC].  ^If the.*
13170 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  * memory pointer
13180 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
13190 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
131a0 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20  ENABLE_MEMSYS3] 
131b0 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  or.** [SQLITE_EN
131c0 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72  ABLE_MEMSYS5] ar
131d0 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20  e defined, then 
131e0 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  the alternative 
131f0 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
13200 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74  tor is engaged t
13210 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20  o handle all of 
13220 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61  SQLites memory a
13230 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
13240 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f  .** The first po
13250 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
13260 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20  y pointer) must 
13270 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
13280 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64   8-byte.** bound
13290 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
132a0 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
132b0 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64  Lite will be und
132c0 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d  efined..** The m
132d0 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
132e0 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64  n size is capped
132f0 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f   at 2**12. Reaso
13300 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20  nable values.** 
13310 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  for the minimum 
13320 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
13330 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68  are 2**5 through
13340 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   2**8.</dd>.**.*
13350 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13360 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  G_MUTEX]] <dt>SQ
13370 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
13380 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
13390 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
133a0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
133b0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
133c0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
133d0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
133e0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
133f0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
13400 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
13410 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
13420 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
13430 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69  evel mutex routi
13440 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
13450 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d  n place.** the m
13460 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75  utex routines bu
13470 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
13480 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
13490 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
134a0 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  ** content of th
134b0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
134c0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
134d0 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63  ure before the c
134e0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
134f0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74  e3_config()] ret
13500 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65  urns. ^If SQLite
13510 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
13520 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
13530 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
13540 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
13550 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
13560 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
13570 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
13580 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
13590 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
135a0 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
135b0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
135c0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
135d0 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
135e0 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e  CONFIG_MUTEX con
135f0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
13600 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
13610 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
13620 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13630 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
13640 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
13650 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
13660 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
13670 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
13680 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
13690 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
136a0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
136b0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
136c0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
136d0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
136e0 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  re.  The.** [sql
136f0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
13700 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
13710 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
13720 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
13730 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74  fined mutex rout
13740 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
13750 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
13760 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
13770 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78  he default mutex
13780 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
13790 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
137a0 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74  rapper used to t
137b0 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65  rack mutex usage
137c0 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65   for performance
137d0 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72  .** profiling or
137e0 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78   testing, for ex
137f0 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c  ample.   ^If SQL
13800 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
13810 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
13820 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
13830 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
13840 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
13850 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
13860 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
13870 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
13880 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
13890 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
138a0 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
138b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
138c0 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
138d0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
138e0 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
138f0 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
13900 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
13910 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
13920 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13930 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64  G_LOOKASIDE]] <d
13940 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13950 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
13960 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
13970 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
13980 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
13990 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61  termine the defa
139a0 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ult.** memory al
139b0 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  location for the
139c0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
139d0 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65  y allocator on e
139e0 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ach.** [database
139f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
13a00 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
13a10 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
13a20 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
13a30 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61  de buffer slot a
13a40 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73  nd the second is
13a50 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
13a60 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65  * slots allocate
13a70 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  d to each databa
13a80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e  se connection.)^
13a90 20 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20    ^(This option 
13aa0 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64  sets the.** <i>d
13ab0 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61  efault</i> looka
13ac0 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b  side size. The [
13ad0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
13ae0 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65  LOOKASIDE].** ve
13af0 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  rb to [sqlite3_d
13b00 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20  b_config()] can 
13b10 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67  be used to chang
13b20 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a  e the lookaside.
13b30 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
13b40 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63   on individual c
13b50 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f  onnections.)^ </
13b60 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13b70 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
13b80 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  2]] <dt>SQLITE_C
13b90 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64  ONFIG_PCACHE2</d
13ba0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
13bb0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
13bc0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
13bd0 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
13be0 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71  ter to.** an [sq
13bf0 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
13c00 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
13c10 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63  This object spec
13c20 69 66 69 65 73 20 74 68 65 20 69 6e 74 65 72 66  ifies the interf
13c30 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74  ace.** to a cust
13c40 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  om page cache im
13c50 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20  plementation.)^ 
13c60 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
13c70 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
13c80 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20  object and uses 
13c90 69 74 20 66 6f 72 20 70 61 67 65 20 63 61 63 68  it for page cach
13ca0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
13cb0 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ions.</dd>.**.**
13cc0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13cd0 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64  _GETPCACHE2]] <d
13ce0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13cf0 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  GETPCACHE2</dt>.
13d00 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
13d10 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
13d20 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
13d30 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
13d40 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
13d50 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
13d60 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c  s2] object.  SQL
13d70 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68  ite copies of th
13d80 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67  e current.** pag
13d90 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
13da0 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74  tation into that
13db0 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e   object.)^ </dd>
13dc0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13dd0 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74  CONFIG_LOG]] <dt
13de0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
13df0 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OG</dt>.** <dd> 
13e00 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
13e10 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20  G_LOG option is 
13e20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72  used to configur
13e30 65 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20  e the SQLite.** 
13e40 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f  global [error lo
13e50 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c  g]..** (^The SQL
13e60 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f  ITE_CONFIG_LOG o
13e70 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
13e80 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69  arguments: a poi
13e90 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e  nter to a.** fun
13ea0 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c  ction with a cal
13eb0 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76  l signature of v
13ec0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  oid(*)(void*,int
13ed0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a  ,const char*), .
13ee0 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72  ** and a pointer
13ef0 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68   to void. ^If th
13f00 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  e function point
13f10 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  er is not NULL, 
13f20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64  it is.** invoked
13f30 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67   by [sqlite3_log
13f40 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65  ()] to process e
13f50 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e  ach logging even
13f60 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66  t.  ^If the.** f
13f70 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
13f80 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71  is NULL, the [sq
13f90 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74  lite3_log()] int
13fa0 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61  erface becomes a
13fb0 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20   no-op..** ^The 
13fc0 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61  void pointer tha
13fd0 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  t is the second 
13fe0 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49  argument to SQLI
13ff0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73  TE_CONFIG_LOG is
14000 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75  .** passed throu
14010 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20  gh as the first 
14020 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
14030 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
14040 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
14050 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72  unction whenever
14060 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69   that function i
14070 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65  s invoked.  ^The
14080 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
14090 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67  r to.** the logg
140a0 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  er function is a
140b0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72   copy of the fir
140c0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
140d0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
140e0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  g.** [sqlite3_lo
140f0 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73  g()] call and is
14100 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20   intended to be 
14110 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  a [result code] 
14120 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64  or an.** [extend
14130 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e  ed result code].
14140 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72    ^The third par
14150 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f  ameter passed to
14160 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a   the logger is.*
14170 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66  * log message af
14180 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76  ter formatting v
14190 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ia [sqlite3_snpr
141a0 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  intf()]..** The 
141b0 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69  SQLite logging i
141c0 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
141d0 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c  reentrant; the l
141e0 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a  ogger function.*
141f0 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68  * supplied by th
14200 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
14210 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e  st not invoke an
14220 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  y SQLite interfa
14230 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74  ce..** In a mult
14240 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69  i-threaded appli
14250 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c  cation, the appl
14260 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
14270 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69  logger.** functi
14280 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  on must be threa
14290 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a  dsafe. </dd>.**.
142a0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
142b0 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c  IG_URI]] <dt>SQL
142c0 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a  ITE_CONFIG_URI.*
142d0 2a 20 3c 64 64 3e 5e 28 54 68 69 73 20 6f 70 74  * <dd>^(This opt
142e0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
142f0 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  le argument of t
14300 79 70 65 20 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d  ype int. If non-
14310 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55 52  zero, then.** UR
14320 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
14330 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20  obally enabled. 
14340 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
14350 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 55   is zero, then U
14360 52 49 20 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69  RI handling.** i
14370 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
14380 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 49 20 68  led.)^ ^If URI h
14390 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
143a0 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c  lly enabled, all
143b0 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70 61   filenames.** pa
143c0 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33  ssed to [sqlite3
143d0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
143e0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 5b  e3_open_v2()], [
143f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
14400 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65  ] or.** specifie
14410 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54  d as part of [AT
14420 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61  TACH] commands a
14430 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
14440 73 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65  s URIs, regardle
14450 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72  ss.** of whether
14460 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c   or not the [SQL
14470 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
14480 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74  ag is set when t
14490 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
144a0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65  onnection is ope
144b0 6e 65 64 2e 20 5e 49 66 20 69 74 20 69 73 20 67  ned. ^If it is g
144c0 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  lobally disabled
144d0 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a  , filenames are.
144e0 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65  ** only interpre
144f0 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20 74  ted as URIs if t
14500 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  he SQLITE_OPEN_U
14510 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 77  RI flag is set w
14520 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  hen the.** datab
14530 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
14540 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 64  s opened. ^(By d
14550 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64  efault, URI hand
14560 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
14570 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68  .** disabled. Th
14580 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  e default value 
14590 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62  may be changed b
145a0 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68  y compiling with
145b0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
145c0 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20  USE_URI] symbol 
145d0 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  defined.)^.**.**
145e0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
145f0 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
14600 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  SCAN]] <dt>SQLIT
14610 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e  E_CONFIG_COVERIN
14620 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20  G_INDEX_SCAN.** 
14630 3c 64 64 3e 5e 54 68 69 73 20 6f 70 74 69 6f 6e  <dd>^This option
14640 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
14650 69 6e 74 65 67 65 72 20 61 72 67 75 6d 65 6e 74  integer argument
14660 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70   which is interp
14670 72 65 74 65 64 20 61 73 0a 2a 2a 20 61 20 62 6f  reted as.** a bo
14680 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74  olean in order t
14690 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
146a0 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63  ble the use of c
146b0 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20  overing indices 
146c0 66 6f 72 0a 2a 2a 20 66 75 6c 6c 20 74 61 62 6c  for.** full tabl
146d0 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71  e scans in the q
146e0 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 20  uery optimizer. 
146f0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65   ^The default se
14700 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69  tting is determi
14710 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53  ned.** by the [S
14720 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45  QLITE_ALLOW_COVE
14730 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d  RING_INDEX_SCAN]
14740 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
14750 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22  tion, or is "on"
14760 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70  .** if that comp
14770 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
14780 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54  is omitted..** T
14790 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69  he ability to di
147a0 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66  sable the use of
147b0 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65   covering indice
147c0 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65  s for full table
147d0 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63   scans.** is bec
147e0 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72  ause some incorr
147f0 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61  ectly coded lega
14800 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  cy applications 
14810 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f  might malfunctio
14820 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70  n.** when the op
14830 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e  timization is en
14840 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e  abled.  Providin
14850 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f  g the ability to
14860 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20  .** disable the 
14870 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c  optimization all
14880 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62  ows the older, b
14890 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  uggy application
148a0 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   code to work.**
148b0 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20   without change 
148c0 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20  even with newer 
148d0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
148e0 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  te..**.** [[SQLI
148f0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
14900 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ]] [[SQLITE_CONF
14910 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a  IG_GETPCACHE]].*
14920 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
14930 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53  FIG_PCACHE and S
14940 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14950 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54  PCACHE.** <dd> T
14960 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65  hese options are
14970 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68   obsolete and sh
14980 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64  ould not be used
14990 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a   by new code..**
149a0 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e   They are retain
149b0 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
149c0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62   compatibility b
149d0 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70  ut are now no-op
149e0 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  s..** </dd>.**.*
149f0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14a00 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64  G_SQLLOG]].** <d
14a10 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14a20 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68  SQLLOG.** <dd>Th
14a30 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c  is option is onl
14a40 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73  y available if s
14a50 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  qlite is compile
14a60 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
14a70 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c  QLITE_ENABLE_SQL
14a80 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73  LOG] pre-process
14a90 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64  or macro defined
14aa0 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  . The first argu
14ab0 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62  ment should.** b
14ac0 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
14ad0 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70   function of typ
14ae0 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  e void(*)(void*,
14af0 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63  sqlite3*,const c
14b00 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54  har*, int)..** T
14b10 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64  he second should
14b20 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69   be of type (voi
14b30 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63  d*). The callbac
14b40 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20  k is invoked by 
14b50 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69  the library.** i
14b60 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 74 65  n three separate
14b70 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20   circumstances, 
14b80 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
14b90 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
14ba0 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  s the.** fourth 
14bb0 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68  parameter. If th
14bc0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
14bd0 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68  er is 0, then th
14be0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
14bf0 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20  ction.** passed 
14c00 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
14c10 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20  gument has just 
14c20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65  been opened. The
14c30 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a   third argument.
14c40 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62  ** points to a b
14c50 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67  uffer containing
14c60 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
14c70 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
14c80 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66  ile. If the.** f
14c90 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
14ca0 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53  is 1, then the S
14cb0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  QL statement tha
14cc0 74 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  t the third para
14cd0 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20  meter.** points 
14ce0 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e  to has just been
14cf0 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69   executed. Or, i
14d00 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
14d10 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 65  ameter is 2, the
14d20 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74  n.** the connect
14d30 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64  ion being passed
14d40 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
14d50 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e  arameter is bein
14d60 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a  g closed. The.**
14d70 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
14d80 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20   is passed NULL 
14d90 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20 41  In this case.  A
14da0 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69  n example of usi
14db0 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69  ng this.** confi
14dc0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
14dd0 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74  can be seen in t
14de0 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e  he "test_sqllog.
14df0 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69  c" source file i
14e00 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63  n.** the canonic
14e10 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65  al SQLite source
14e20 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   tree.</dd>.**.*
14e30 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14e40 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a  G_MMAP_SIZE]].**
14e50 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14e60 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20  IG_MMAP_SIZE.** 
14e70 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46  <dd>^SQLITE_CONF
14e80 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b  IG_MMAP_SIZE tak
14e90 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e  es two 64-bit in
14ea0 74 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69  teger (sqlite3_i
14eb0 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20  nt64) values.** 
14ec0 74 68 61 74 20 61 72 65 20 74 68 65 20 64 65 66  that are the def
14ed0 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c  ault mmap size l
14ee0 69 6d 69 74 20 28 74 68 65 20 64 65 66 61 75 6c  imit (the defaul
14ef0 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a  t setting for.**
14f00 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
14f10 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78  ze]) and the max
14f20 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61  imum allowed mma
14f30 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a  p size limit..**
14f40 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65   ^The default se
14f50 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65  tting can be ove
14f60 72 72 69 64 64 65 6e 20 62 79 20 65 61 63 68 20  rridden by each 
14f70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14f80 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74  ion using.** eit
14f90 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20  her the [PRAGMA 
14fa0 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61  mmap_size] comma
14fb0 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20  nd, or by using 
14fc0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  the.** [SQLITE_F
14fd0 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  CNTL_MMAP_SIZE] 
14fe0 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e  file control.  ^
14ff0 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c  (The maximum all
15000 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a  owed mmap size.*
15010 2a 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e  * cannot be chan
15020 67 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 2e  ged at run-time.
15030 20 20 4e 6f 72 20 6d 61 79 20 74 68 65 20 6d 61    Nor may the ma
15040 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d  ximum allowed mm
15050 61 70 20 73 69 7a 65 0a 2a 2a 20 65 78 63 65 65  ap size.** excee
15060 64 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  d the compile-ti
15070 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20  me maximum mmap 
15080 73 69 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a  size set by the.
15090 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d  ** [SQLITE_MAX_M
150a0 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c  MAP_SIZE] compil
150b0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e  e-time option.)^
150c0 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61  .** ^If either a
150d0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20  rgument to this 
150e0 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69  option is negati
150f0 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72  ve, then that ar
15100 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61  gument is.** cha
15110 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70  nged to its comp
15120 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74  ile-time default
15130 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
15140 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
15150 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  APSIZE]].** <dt>
15160 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
15170 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20  N32_HEAPSIZE.** 
15180 3c 64 64 3e 5e 54 68 69 73 20 6f 70 74 69 6f 6e  <dd>^This option
15190 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
151a0 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  le if SQLite is 
151b0 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 69 6e  compiled for Win
151c0 64 6f 77 73 0a 2a 2a 20 77 69 74 68 20 74 68 65  dows.** with the
151d0 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d   [SQLITE_WIN32_M
151e0 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65  ALLOC] pre-proce
151f0 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e  ssor macro defin
15200 65 64 2e 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  ed..** SQLITE_CO
15210 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
15220 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d 62  IZE takes a 32-b
15230 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  it unsigned inte
15240 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61  ger value.** tha
15250 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
15260 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
15270 74 68 65 20 63 72 65 61 74 65 64 20 68 65 61 70  the created heap
15280 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  ..** </dl>.*/.#d
15290 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
152a0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
152b0 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    1  /* nil */.#
152c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
152d0 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
152e0 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     2  /* nil */.
152f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15300 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
15310 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f      3  /* nil */
15320 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15330 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20  CONFIG_MALLOC   
15340 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74       4  /* sqlit
15350 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
15360 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15370 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
15380 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c  OC     5  /* sql
15390 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
153a0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
153b0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
153c0 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76  CH       6  /* v
153d0 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
153e0 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
153f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
15400 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a  ECACHE     7  /*
15410 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
15420 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
15430 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
15440 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20  EAP          8  
15450 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42  /* void*, int nB
15460 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a  yte, int min */.
15470 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15480 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20  ONFIG_MEMSTATUS 
15490 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61      9  /* boolea
154a0 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
154b0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
154c0 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73          10  /* s
154d0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
154e0 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
154f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
15500 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20  ETMUTEX     11  
15510 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
15520 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20  _methods* */./* 
15530 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54  previously SQLIT
15540 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c  E_CONFIG_CHUNKAL
15550 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20  LOC 12 which is 
15560 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a  now unused. */ .
15570 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15580 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
15590 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e     13  /* int in
155a0 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
155b0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
155c0 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e  E       14  /* n
155d0 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20  o-op */.#define 
155e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
155f0 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f  TPCACHE    15  /
15600 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69  * no-op */.#defi
15610 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15620 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 36  _LOG          16
15630 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64    /* xFunc, void
15640 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
15650 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20  ITE_CONFIG_URI  
15660 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69          17  /* i
15670 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
15680 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
15690 48 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20  HE2      18  /* 
156a0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
156b0 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66  ethods2* */.#def
156c0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
156d0 47 5f 47 45 54 50 43 41 43 48 45 32 20 20 20 31  G_GETPCACHE2   1
156e0 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63  9  /* sqlite3_pc
156f0 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a  ache_methods2* *
15700 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15710 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
15720 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20  _INDEX_SCAN 20  
15730 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  /* int */.#defin
15740 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15750 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20  SQLLOG       21 
15760 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69   /* xSqllog, voi
15770 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d* */.#define SQ
15780 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
15790 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a 20  _SIZE    22  /* 
157a0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20 73  sqlite3_int64, s
157b0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a  qlite3_int64 */.
157c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
157d0 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
157e0 53 49 5a 45 20 20 20 20 20 20 32 33 20 20 2f 2a  SIZE      23  /*
157f0 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f   int nByte */../
15800 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
15810 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
15820 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  on Configuration
15830 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54   Options.**.** T
15840 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
15850 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
15860 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
15870 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
15880 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
15890 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
158a0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  nd argument to t
158b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
158c0 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
158d0 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
158e0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
158f0 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
15900 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
15910 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
15920 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
15930 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
15940 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
15950 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
15960 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
15970 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
15980 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
15990 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
159a0 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
159b0 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
159c0 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71  orked.  ^The [sq
159d0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
159e0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
159f0 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f  l return a.** no
15a00 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
15a10 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74  de] if a discont
15a20 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f  inued or unsuppo
15a30 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69  rted configurati
15a40 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20  on option.** is 
15a50 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  invoked..**.** <
15a60 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  dl>.** <dt>SQLIT
15a70 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
15a80 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
15a90 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  > ^This option t
15aa0 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74  akes three addit
15ab0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20  ional arguments 
15ac0 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74  that determine t
15ad0 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64  he .** [lookasid
15ae0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
15af0 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  or] configuratio
15b00 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62  n for the [datab
15b10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
15b20 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
15b30 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69  rgument (the thi
15b40 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
15b50 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
15b60 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f  ig()] is a.** po
15b70 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
15b80 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20  y buffer to use 
15b90 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  for lookaside me
15ba0 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  mory..** ^The fi
15bb0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74  rst argument aft
15bc0 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42  er the SQLITE_DB
15bd0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
15be0 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20   verb.** may be 
15bf0 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61  NULL in which ca
15c00 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  se SQLite will a
15c10 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c  llocate the.** l
15c20 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
15c30 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71  itself using [sq
15c40 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
15c50 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
15c60 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
15c70 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
15c80 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
15c90 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  ot.  ^The third 
15ca0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
15cb0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
15cc0 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  ts.  The size of
15cd0 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74   the buffer in t
15ce0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
15cf0 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65  t must be greate
15d00 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75  r than.** or equ
15d10 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63  al to the produc
15d20 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  t of the second 
15d30 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65  and third argume
15d40 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72  nts.  The buffer
15d50 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67  .** must be alig
15d60 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
15d70 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20   boundary.  ^If 
15d80 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
15d90 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45  ent to.** SQLITE
15da0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
15db0 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c  IDE is not a mul
15dc0 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69  tiple of 8, it i
15dd0 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  s internally.** 
15de0 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20  rounded down to 
15df0 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72  the next smaller
15e00 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20   multiple of 8. 
15e10 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65   ^(The lookaside
15e20 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69   memory.** confi
15e30 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64  guration for a d
15e40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15e50 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63  on can only be c
15e60 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74  hanged when that
15e70 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
15e80 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
15e90 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20  using lookaside 
15ea0 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74  memory, or in ot
15eb0 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65  her words.** whe
15ec0 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76  n the "current v
15ed0 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62  alue" returned b
15ee0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62  y.** [sqlite3_db
15ef0 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49  _status](D,[SQLI
15f00 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
15f10 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72  IDE],...) is zer
15f20 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  o..** Any attemp
15f30 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  t to change the 
15f40 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
15f50 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77   configuration w
15f60 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  hen lookaside.**
15f70 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73   memory is in us
15f80 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e  e leaves the con
15f90 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61  figuration uncha
15fa0 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73  nged and returns
15fb0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53   .** [SQLITE_BUS
15fc0 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  Y].)^</dd>.**.**
15fd0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
15fe0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59  NFIG_ENABLE_FKEY
15ff0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
16000 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
16010 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
16020 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f  disable the enfo
16030 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66  rcement of.** [f
16040 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74  oreign key const
16050 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20  raints].  There 
16060 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
16070 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
16080 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
16090 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
160a0 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
160b0 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b   0 to disable FK
160c0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a   enforcement,.**
160d0 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
160e0 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
160f0 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  nt or negative t
16100 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72  o leave FK enfor
16110 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e  cement.** unchan
16120 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ged.  The second
16130 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
16140 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
16150 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
16160 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
16170 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
16180 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66  e whether FK enf
16190 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20  orcement is off 
161a0 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  or on.** followi
161b0 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
161c0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
161d0 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
161e0 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
161f0 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
16200 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73  FK enforcement s
16210 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
16220 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
16230 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
16240 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
16250 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e  BLE_TRIGGER</dt>
16260 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
16270 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
16280 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
16290 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47  le [CREATE TRIGG
162a0 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a  ER | triggers]..
162b0 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  ** There should 
162c0 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
162d0 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
162e0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
162f0 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  nt is an integer
16300 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64   which is 0 to d
16310 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c  isable triggers,
16320 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
16330 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20  enable triggers 
16340 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
16350 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67  eave the setting
16360 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54   unchanged..** T
16370 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
16380 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
16390 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69   to an integer i
163a0 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  nto which.** is 
163b0 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
163c0 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
163d0 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20  er triggers are 
163e0 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62  disabled or enab
163f0 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  led.** following
16400 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
16410 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
16420 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20  r may be a NULL 
16430 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77  pointer, in.** w
16440 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72  hich case the tr
16450 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73  igger setting is
16460 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
16470 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
16480 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
16490 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
164a0 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20  _LOOKASIDE      
164b0 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20   1001  /* void* 
164c0 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69  int int */.#defi
164d0 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
164e0 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20  IG_ENABLE_FKEY  
164f0 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74 20     1002  /* int 
16500 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
16510 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
16520 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20  ENABLE_TRIGGER  
16530 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74  1003  /* int int
16540 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  * */.../*.** CAP
16550 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72  I3REF: Enable Or
16560 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65   Disable Extende
16570 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  d Result Codes.*
16580 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
16590 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
165a0 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e  t_codes() routin
165b0 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  e enables or dis
165c0 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78  ables the.** [ex
165d0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
165e0 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20  des] feature of 
165f0 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74  SQLite. ^The ext
16600 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20  ended result.** 
16610 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c  codes are disabl
16620 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f  ed by default fo
16630 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d  r historical com
16640 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69  patibility..*/.i
16650 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
16660 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
16670 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
16680 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  noff);../*.** CA
16690 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73  PI3REF: Last Ins
166a0 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20  ert Rowid.**.** 
166b0 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d  ^Each entry in m
166c0 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65  ost SQLite table
166d0 73 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57  s (except for [W
166e0 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61  ITHOUT ROWID] ta
166f0 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75  bles).** has a u
16700 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67  nique 64-bit sig
16710 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b  ned.** integer k
16720 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52  ey called the [R
16730 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e  OWID | "rowid"].
16740 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61   ^The rowid is a
16750 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a  lways available.
16760 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61  ** as an undecla
16770 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64  red column named
16780 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20   ROWID, OID, or 
16790 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20  _ROWID_ as long 
167a0 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65  as those.** name
167b0 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75  s are not also u
167c0 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c  sed by explicitl
167d0 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
167e0 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74  ns. ^If.** the t
167f0 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d  able has a colum
16800 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47  n of type [INTEG
16810 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
16820 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  then that column
16830 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61  .** is another a
16840 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77  lias for the row
16850 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  id..**.** ^The s
16860 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
16870 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65  rt_rowid(D) inte
16880 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
16890 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
168a0 20 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74   .** most recent
168b0 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
168c0 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69  ERT] into a rowi
168d0 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74  d table or [virt
168e0 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e  ual table].** on
168f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
16900 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65  tion D..** ^Inse
16910 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55  rts into [WITHOU
16920 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20  T ROWID] tables 
16930 61 72 65 20 6e 6f 74 20 72 65 63 6f 72 64 65 64  are not recorded
16940 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63  ..** ^If no succ
16950 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73  essful [INSERT]s
16960 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c   into rowid tabl
16970 65 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20  es.** have ever 
16980 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 65 20  occurred on the 
16990 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
169a0 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20  ion D, .** then 
169b0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
169c0 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74  ert_rowid(D) ret
169d0 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
169e0 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54   ^(If an [INSERT
169f0 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  ] occurs within 
16a00 61 20 74 72 69 67 67 65 72 20 6f 72 20 77 69 74  a trigger or wit
16a10 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74  hin a [virtual t
16a20 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c  able].** method,
16a30 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
16a40 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74  ne will return t
16a50 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
16a60 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f  e inserted.** ro
16a70 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  w as long as the
16a80 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
16a90 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64  ual table method
16aa0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20   is running..** 
16ab0 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69  But once the tri
16ac0 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20  gger or virtual 
16ad0 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64  table method end
16ae0 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  s, the value ret
16af0 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69  urned .** by thi
16b00 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74  s routine revert
16b10 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73  s to what it was
16b20 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67   before the trig
16b30 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a  ger or virtual.*
16b40 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62  * table method b
16b50 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41  egan.)^.**.** ^A
16b60 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20  n [INSERT] that 
16b70 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63  fails due to a c
16b80 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
16b90 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20  ion is not a.** 
16ba0 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
16bb0 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  RT] and does not
16bc0 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
16bd0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
16be0 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20  is.** routine.  
16bf0 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20  ^Thus INSERT OR 
16c00 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20  FAIL, INSERT OR 
16c10 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f  IGNORE, INSERT O
16c20 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61  R ROLLBACK,.** a
16c30 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f  nd INSERT OR ABO
16c40 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67  RT make no chang
16c50 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e  es to the return
16c60 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a   value of this.*
16c70 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74  * routine when t
16c80 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66  heir insertion f
16c90 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e  ails.  ^(When IN
16ca0 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a  SERT OR REPLACE.
16cb0 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20  ** encounters a 
16cc0 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
16cd0 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f  tion, it does no
16ce0 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20  t fail.  The.** 
16cf0 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73  INSERT continues
16d00 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61   to completion a
16d10 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f  fter deleting ro
16d20 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a  ws that caused.*
16d30 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74  * the constraint
16d40 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45   problem so INSE
16d50 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69  RT OR REPLACE wi
16d60 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65  ll always change
16d70 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76  .** the return v
16d80 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74  alue of this int
16d90 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  erface.)^.**.** 
16da0 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65  ^For the purpose
16db0 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  s of this routin
16dc0 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69  e, an [INSERT] i
16dd0 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a  s considered to.
16de0 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c  ** be successful
16df0 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73   even if it is s
16e00 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c  ubsequently roll
16e10 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54  ed back..**.** T
16e20 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
16e30 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51  accessible to SQ
16e40 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61  L statements via
16e50 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e   the.** [last_in
16e60 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c  sert_rowid() SQL
16e70 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
16e80 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
16e90 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20  thread performs 
16ea0 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f  a new [INSERT] o
16eb0 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61  n the same.** da
16ec0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16ed0 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c  n while the [sql
16ee0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
16ef0 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e  _rowid()].** fun
16f00 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
16f10 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65   and thus change
16f20 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72  s the last inser
16f30 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68  t [rowid],.** th
16f40 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
16f50 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
16f60 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
16f70 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70  wid()] is.** unp
16f80 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d  redictable and m
16f90 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65  ight not equal e
16fa0 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72  ither the old or
16fb0 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74   the new.** last
16fc0 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e   insert [rowid].
16fd0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
16fe0 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  4 sqlite3_last_i
16ff0 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69  nsert_rowid(sqli
17000 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
17010 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68  PI3REF: Count Th
17020 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  e Number Of Rows
17030 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20   Modified.**.** 
17040 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
17050 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
17060 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f  r of database ro
17070 77 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61  ws that were cha
17080 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72  nged.** or inser
17090 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62  ted or deleted b
170a0 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  y the most recen
170b0 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51  tly completed SQ
170c0 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f  L statement.** o
170d0 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  n the [database 
170e0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
170f0 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72  ified by the fir
17100 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  st parameter..**
17110 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20   ^(Only changes 
17120 74 68 61 74 20 61 72 65 20 64 69 72 65 63 74 6c  that are directl
17130 79 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  y specified by t
17140 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50  he [INSERT], [UP
17150 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45  DATE],.** or [DE
17160 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 20  LETE] statement 
17170 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75  are counted.  Au
17180 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20  xiliary changes 
17190 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69  caused by.** tri
171a0 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 65 69 67  ggers or [foreig
171b0 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61  n key actions] a
171c0 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29  re not counted.)
171d0 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71  ^ Use the.** [sq
171e0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
171f0 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20  ges()] function 
17200 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61  to find the tota
17210 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e  l number of chan
17220 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67  ges.** including
17230 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
17240 62 79 20 74 72 69 67 67 65 72 73 20 61 6e 64 20  by triggers and 
17250 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
17260 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e  ons..**.** ^Chan
17270 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68  ges to a view th
17280 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74 65 64  at are simulated
17290 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41 44 20   by an [INSTEAD 
172a0 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61  OF trigger].** a
172b0 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20  re not counted. 
172c0 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c 65   Only real table
172d0 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75   changes are cou
172e0 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20  nted..**.** ^(A 
172f0 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73 20  "row change" is 
17300 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73 69  a change to a si
17310 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73 69  ngle row of a si
17320 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61  ngle table.** ca
17330 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45 52  used by an INSER
17340 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55 50  T, DELETE, or UP
17350 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e 20  DATE statement. 
17360 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61 72   Rows that.** ar
17370 65 20 63 68 61 6e 67 65 64 20 61 73 20 73 69 64  e changed as sid
17380 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b 52 45  e effects of [RE
17390 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e  PLACE] constrain
173a0 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a  t resolution,.**
173b0 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54   rollback, ABORT
173c0 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52   processing, [DR
173d0 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79  OP TABLE], or by
173e0 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65   any other.** me
173f0 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20  chanisms do not 
17400 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74 20  count as direct 
17410 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a  row changes.)^.*
17420 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20  *.** A "trigger 
17430 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73 63  context" is a sc
17440 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e  ope of execution
17450 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64   that begins and
17460 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68  .** ends with th
17470 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 5b 43  e script of a [C
17480 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
17490 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f  trigger]. .** Mo
174a0 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
174b0 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74  s are.** evaluat
174c0 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  ed outside of an
174d0 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 69 73  y trigger.  This
174e0 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65 76   is the "top lev
174f0 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 63  el".** trigger c
17500 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74 72  ontext.  If a tr
17510 69 67 67 65 72 20 66 69 72 65 73 20 66 72 6f 6d  igger fires from
17520 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20   the top level, 
17530 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 72  a.** new trigger
17540 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 65   context is ente
17550 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 72 61  red for the dura
17560 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65  tion of that one
17570 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53 75  .** trigger.  Su
17580 62 74 72 69 67 67 65 72 73 20 63 72 65 61 74 65  btriggers create
17590 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f 72   subcontexts for
175a0 20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e 2e   their duration.
175b0 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
175c0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
175d0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   or [sqlite3_ste
175e0 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79  p()] recursively
175f0 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65   does.** not cre
17600 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67 65  ate a new trigge
17610 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
17620 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
17630 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
17640 65 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77  er of direct row
17650 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a   changes in the.
17660 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49  ** most recent I
17670 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
17680 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
17690 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  nt within the sa
176a0 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f  me.** trigger co
176b0 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ntext..**.** ^Th
176c0 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20  us, when called 
176d0 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76  from the top lev
176e0 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  el, this functio
176f0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  n returns the.**
17700 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67   number of chang
17710 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72  es in the most r
17720 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50  ecent INSERT, UP
17730 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
17740 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63  ** that also occ
17750 75 72 72 65 64 20 61 74 20 74 68 65 20 74 6f 70  urred at the top
17760 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74 68 69   level.  ^(Withi
17770 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20  n the body of a 
17780 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20  trigger,.** the 
17790 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
177a0 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  ) interface can 
177b0 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e  be called to fin
177c0 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  d the number of.
177d0 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ** changes in th
177e0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
177f0 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54  completed INSERT
17800 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
17810 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ETE.** statement
17820 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79   within the body
17830 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72 69   of the same tri
17840 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  gger..** However
17850 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74  , the number ret
17860 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69  urned does not i
17870 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a 2a  nclude changes.*
17880 2a 20 63 61 75 73 65 64 20 62 79 20 73 75 62 74  * caused by subt
17890 72 69 67 67 65 72 73 20 73 69 6e 63 65 20 74 68  riggers since th
178a0 6f 73 65 20 68 61 76 65 20 74 68 65 69 72 20 6f  ose have their o
178b0 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a  wn context.)^.**
178c0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
178d0 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
178e0 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72  changes()] inter
178f0 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f  face, the.** [co
17900 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67  unt_changes prag
17910 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68  ma], and the [ch
17920 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
17930 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
17940 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
17950 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
17960 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
17970 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
17980 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
17990 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  3_changes()] is 
179a0 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
179b0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
179c0 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ** is unpredicta
179d0 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
179e0 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  ingful..*/.int s
179f0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73  qlite3_changes(s
17a00 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
17a10 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c   CAPI3REF: Total
17a20 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
17a30 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e  Modified.**.** ^
17a40 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
17a50 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
17a60 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20   of row changes 
17a70 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52  caused by [INSER
17a80 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20  T],.** [UPDATE] 
17a90 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74  or [DELETE] stat
17aa0 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65  ements since the
17ab0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
17ac0 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65  ction] was opene
17ad0 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e  d..** ^(The coun
17ae0 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  t returned by sq
17af0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
17b00 67 65 73 28 29 20 69 6e 63 6c 75 64 65 73 20 61  ges() includes a
17b10 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72  ll changes.** fr
17b20 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45 20 54  om all [CREATE T
17b30 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
17b40 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 63  ] contexts and c
17b50 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79 0a 2a  hanges made by.*
17b60 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  * [foreign key a
17b70 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72  ctions]. However
17b80 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64  ,.** the count d
17b90 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
17ba0 63 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20  changes used to 
17bb0 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41  implement [REPLA
17bc0 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c  CE] constraints,
17bd0 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73  .** do rollbacks
17be0 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73   or ABORT proces
17bf0 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54  sing, or [DROP T
17c00 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67  ABLE] processing
17c10 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20  .  The.** count 
17c20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
17c30 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74   rows of views t
17c40 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53  hat fire an [INS
17c50 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d  TEAD OF trigger]
17c60 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74  ,.** though if t
17c70 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72  he INSTEAD OF tr
17c80 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e  igger makes chan
17c90 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20  ges of its own, 
17ca0 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a  those changes .*
17cb0 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e  * are counted.)^
17cc0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
17cd0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
17ce0 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73   function counts
17cf0 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 73 20   the changes as 
17d00 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73  soon as.** the s
17d10 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61  tatement that ma
17d20 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70  kes them is comp
17d30 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 20  leted (when the 
17d40 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  statement handle
17d50 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 74 6f  .** is passed to
17d60 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
17d70 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
17d80 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a  inalize()])..**.
17d90 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
17da0 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
17db0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74  ()] interface, t
17dc0 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61  he.** [count_cha
17dd0 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e  nges pragma], an
17de0 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61  d the [total_cha
17df0 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
17e00 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
17e10 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
17e20 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
17e30 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
17e40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
17e50 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  * while [sqlite3
17e60 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
17e70 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
17e80 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72  n the value.** r
17e90 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65  eturned is unpre
17ea0 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
17eb0 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
17ec0 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61  int sqlite3_tota
17ed0 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  l_changes(sqlite
17ee0 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
17ef0 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20  3REF: Interrupt 
17f00 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51  A Long-Running Q
17f10 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  uery.**.** ^This
17f20 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
17f30 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74   any pending dat
17f40 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20  abase operation 
17f50 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20  to abort and.** 
17f60 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61  return at its ea
17f70 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69  rliest opportuni
17f80 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65  ty. This routine
17f90 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a   is typically.**
17fa0 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f   called in respo
17fb0 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63  nse to a user ac
17fc0 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65  tion such as pre
17fd0 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a  ssing "Cancel".*
17fe0 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72  * or Ctrl-C wher
17ff0 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73  e the user wants
18000 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70   a long query op
18010 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a  eration to halt.
18020 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ** immediately..
18030 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66  **.** ^It is saf
18040 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
18050 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68  outine from a th
18060 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66  read different f
18070 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61  rom the.** threa
18080 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e  d that is curren
18090 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20  tly running the 
180a0 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
180b0 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69  on.  But it.** i
180c0 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61  s not safe to ca
180d0 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
180e0 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
180f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
18100 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f  t.** is closed o
18110 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65  r might close be
18120 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  fore sqlite3_int
18130 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73  errupt() returns
18140 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53  ..**.** ^If an S
18150 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
18160 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69  very nearly fini
18170 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65  shed at the time
18180 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   when.** sqlite3
18190 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20  _interrupt() is 
181a0 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20  called, then it 
181b0 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61  might not have a
181c0 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a  n opportunity.**
181d0 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74   to be interrupt
181e0 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e  ed and might con
181f0 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74  tinue to complet
18200 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53  ion..**.** ^An S
18210 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  QL operation tha
18220 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64  t is interrupted
18230 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
18240 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e  LITE_INTERRUPT].
18250 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65  .** ^If the inte
18260 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72  rrupted SQL oper
18270 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45  ation is an INSE
18280 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
18290 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73  ELETE.** that is
182a0 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69   inside an expli
182b0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
182c0 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65   then the entire
182d0 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20   transaction.** 
182e0 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62  will be rolled b
182f0 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
18300 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
18310 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
18320 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66  D) call is in ef
18330 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63  fect until all c
18340 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
18350 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
18360 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ts on [database 
18370 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f  connection] D co
18380 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65  mplete.  ^Any ne
18390 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
183a0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
183b0 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
183c0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
183d0 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f  () call and befo
183e0 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69  re the .** runni
183f0 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65  ng statements re
18400 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69  aches zero are i
18410 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66  nterrupted as if
18420 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a   they had been.*
18430 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20  * running prior 
18440 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  to the sqlite3_i
18450 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e  nterrupt() call.
18460 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65    ^New SQL state
18470 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
18480 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
18490 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  the running stat
184a0 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63  ement count reac
184b0 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20  hes zero are.** 
184c0 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20  not effected by 
184d0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
184e0 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63  rrupt()..** ^A c
184f0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
18500 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74  nterrupt(D) that
18510 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65   occurs when the
18520 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e  re are no runnin
18530 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  g.** SQL stateme
18540 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61  nts is a no-op a
18550 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74  nd has no effect
18560 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   on SQL statemen
18570 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
18580 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
18590 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
185a0 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e  pt() call return
185b0 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  s..**.** If the 
185c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
185d0 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65  ion closes while
185e0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
185f0 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e  upt()].** is run
18600 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68  ning then bad th
18610 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  ings will likely
18620 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64   happen..*/.void
18630 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
18640 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  pt(sqlite3*);../
18650 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
18660 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53  etermine If An S
18670 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20  QL Statement Is 
18680 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54  Complete.**.** T
18690 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
186a0 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20  e useful during 
186b0 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70  command-line inp
186c0 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ut to determine 
186d0 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  if the.** curren
186e0 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74  tly entered text
186f0 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61   seems to form a
18700 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
18710 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66  atement or.** if
18720 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75   additional inpu
18730 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f  t is needed befo
18740 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74  re sending the t
18750 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69  ext into.** SQLi
18760 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20  te for parsing. 
18770 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
18780 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65   return 1 if the
18790 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a   input string.**
187a0 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61   appears to be a
187b0 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
187c0 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61  atement.  ^A sta
187d0 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64  tement is judged
187e0 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65   to be.** comple
187f0 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69  te if it ends wi
18800 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74  th a semicolon t
18810 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20  oken and is not 
18820 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a  a prefix of a.**
18830 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45   well-formed CRE
18840 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74  ATE TRIGGER stat
18850 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c  ement.  ^Semicol
18860 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62  ons that are emb
18870 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  edded within.** 
18880 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20  string literals 
18890 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69  or quoted identi
188a0 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f  fier names or co
188b0 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a  mments are not.*
188c0 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f  * independent to
188d0 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70  kens (they are p
188e0 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e  art of the token
188f0 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61   in which they a
18900 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20  re.** embedded) 
18910 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20  and thus do not 
18920 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65  count as a state
18930 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e  ment terminator.
18940 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a    ^Whitespace.**
18950 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68   and comments th
18960 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69  at follow the fi
18970 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72  nal semicolon ar
18980 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  e ignored..**.**
18990 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
189a0 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65   return 0 if the
189b0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e   statement is in
189c0 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61  complete.  ^If a
189d0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
189e0 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65  ation fails, the
189f0 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69  n SQLITE_NOMEM i
18a00 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
18a10 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
18a20 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74  s do not parse t
18a30 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
18a40 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e  s thus.** will n
18a50 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63  ot detect syntac
18a60 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63  tically incorrec
18a70 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  t SQL..**.** ^(I
18a80 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74  f SQLite has not
18a90 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65   been initialize
18aa0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
18ab0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70  _initialize()] p
18ac0 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f  rior .** to invo
18ad0 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d  king sqlite3_com
18ae0 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73  plete16() then s
18af0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
18b00 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
18b10 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
18b20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  by sqlite3_compl
18b30 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61  ete16().  If tha
18b40 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  t initialization
18b50 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20   fails,.** then 
18b60 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
18b70 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
18b80 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20  mplete16() will 
18b90 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72  be non-zero.** r
18ba0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
18bb0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
18bc0 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d  input SQL is com
18bd0 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  plete.)^.**.** T
18be0 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
18bf0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d  ite3_complete()]
18c00 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
18c10 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
18c20 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  F-8 string..**.*
18c30 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
18c40 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
18c50 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  16()] must be a 
18c60 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
18c70 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
18c80 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
18c90 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  order..*/.int sq
18ca0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63  lite3_complete(c
18cb0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b  onst char *sql);
18cc0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d  .int sqlite3_com
18cd0 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f  plete16(const vo
18ce0 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  id *sql);../*.**
18cf0 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73   CAPI3REF: Regis
18d00 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54  ter A Callback T
18d10 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f  o Handle SQLITE_
18d20 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a  BUSY Errors.**.*
18d30 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
18d40 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c  usy_handler(D,X,
18d50 50 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  P) routine sets 
18d60 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
18d70 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69  ion X.** that mi
18d80 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
18d90 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77  ith argument P w
18da0 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74  henever.** an at
18db0 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f  tempt is made to
18dc0 20 61 63 63 65 73 73 20 61 20 64 61 74 61 62 61   access a databa
18dd0 73 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61  se table associa
18de0 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74  ted with.** [dat
18df0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18e00 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72  ] D when another
18e10 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72   thread.** or pr
18e20 6f 63 65 73 73 20 68 61 73 20 74 68 65 20 74 61  ocess has the ta
18e30 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54  ble locked..** T
18e40 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  he sqlite3_busy_
18e50 68 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66  handler() interf
18e60 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 69  ace is used to i
18e70 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c  mplement.** [sql
18e80 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
18e90 74 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41  t()] and [PRAGMA
18ea0 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a   busy_timeout]..
18eb0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75  **.** ^If the bu
18ec0 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
18ed0 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ULL, then [SQLIT
18ee0 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65  E_BUSY].** is re
18ef0 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
18f00 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65  ly upon encounte
18f10 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20  ring the lock.  
18f20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
18f30 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20  lback.** is not 
18f40 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63  NULL, then the c
18f50 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65  allback might be
18f60 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77   invoked with tw
18f70 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a  o arguments..**.
18f80 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
18f90 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75  gument to the bu
18fa0 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20  sy handler is a 
18fb0 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64  copy of the void
18fc0 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a  * pointer which.
18fd0 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20  ** is the third 
18fe0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
18ff0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
19000 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ().  ^The second
19010 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
19020 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
19030 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
19040 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73   number of times
19050 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68   that the busy h
19060 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65  andler has.** be
19070 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74  en invoked for t
19080 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20  he same locking 
19090 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
190a0 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  ** busy callback
190b0 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e   returns 0, then
190c0 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61   no additional a
190d0 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65  ttempts are made
190e0 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68   to.** access th
190f0 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b  e database and [
19100 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20  SQLITE_BUSY] is 
19110 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74  returned.** to t
19120 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a  he application..
19130 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62  ** ^If the callb
19140 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
19150 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68  zero, then anoth
19160 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73  er attempt.** is
19170 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20   made to access 
19180 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
19190 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61   the cycle repea
191a0 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ts..**.** The pr
191b0 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79  esence of a busy
191c0 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f   handler does no
191d0 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  t guarantee that
191e0 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f   it will be invo
191f0 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72  ked.** when ther
19200 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e  e is lock conten
19210 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65  tion. ^If SQLite
19220 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74   determines that
19230 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75   invoking the bu
19240 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f  sy.** handler co
19250 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20  uld result in a 
19260 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c  deadlock, it wil
19270 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72  l go ahead and r
19280 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
19290 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70  SY].** to the ap
192a0 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61  plication instea
192b0 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68  d of invoking th
192c0 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c  e .** busy handl
192d0 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
192e0 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
192f0 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
19300 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
19310 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
19320 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
19330 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
19340 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
19350 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
19360 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
19370 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
19380 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
19390 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
193a0 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
193b0 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
193c0 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
193d0 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
193e0 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
193f0 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
19400 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
19410 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
19420 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
19430 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
19440 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
19450 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
19460 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
19470 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
19480 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
19490 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
194a0 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
194b0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
194c0 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
194d0 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
194e0 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
194f0 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
19500 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
19510 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
19520 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
19530 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
19540 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
19550 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
19560 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  lt busy callback
19570 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
19580 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
19590 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
195a0 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65  y handler define
195b0 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64  d for each.** [d
195c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
195d0 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20  on].  Setting a 
195e0 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72  new busy handler
195f0 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70   clears any.** p
19600 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61  reviously set ha
19610 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20  ndler.)^  ^Note 
19620 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  that calling [sq
19630 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
19640 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c  ut()].** or eval
19650 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62  uating [PRAGMA b
19660 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77  usy_timeout=N] w
19670 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a  ill change the.*
19680 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61  * busy handler a
19690 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e  nd thus clear an
196a0 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74  y previously set
196b0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
196c0 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61  *.** The busy ca
196d0 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f  llback should no
196e0 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f  t take any actio
196f0 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20  ns which modify 
19700 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
19710 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
19720 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
19730 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74   handler.  In ot
19740 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68  her words,.** th
19750 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  e busy handler i
19760 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e  s not reentrant.
19770 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f    Any such actio
19780 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20  ns.** result in 
19790 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
197a0 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73  or..** .** A bus
197b0 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e  y handler must n
197c0 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ot close the dat
197d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
197e0 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64  .** or [prepared
197f0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
19800 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
19810 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e  y handler..*/.in
19820 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  t sqlite3_busy_h
19830 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
19840 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e   int(*)(void*,in
19850 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  t), void*);../*.
19860 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
19870 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a   A Busy Timeout.
19880 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
19890 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69  ine sets a [sqli
198a0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
198b0 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d   | busy handler]
198c0 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20   that sleeps.** 
198d0 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20  for a specified 
198e0 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77  amount of time w
198f0 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c  hen a table is l
19900 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e  ocked.  ^The han
19910 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65  dler.** will sle
19920 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ep multiple time
19930 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74  s until at least
19940 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
19950 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a  ds of sleeping.*
19960 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74  * have accumulat
19970 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c  ed.  ^After at l
19980 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
19990 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
199a0 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c  ng,.** the handl
199b0 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69  er returns 0 whi
199c0 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74  ch causes [sqlit
199d0 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65  e3_step()] to re
199e0 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
199f0 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  BUSY]..**.** ^Ca
19a00 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
19a10 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d  ne with an argum
19a20 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  ent less than or
19a30 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a   equal to zero.*
19a40 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20  * turns off all 
19a50 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a  busy handlers..*
19a60 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
19a70 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
19a80 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
19a90 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  or a particular.
19aa0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
19ab0 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79  nection] any any
19ac0 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20   given moment.  
19ad0 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20  If another busy 
19ae0 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64  handler.** was d
19af0 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b  efined  (using [
19b00 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
19b10 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74  dler()]) prior t
19b20 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69  o calling.** thi
19b30 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20  s routine, that 
19b40 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
19b50 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e  er is cleared.)^
19b60 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
19b70 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74    [PRAGMA busy_t
19b80 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73  imeout].*/.int s
19b90 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
19ba0 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  out(sqlite3*, in
19bb0 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t ms);../*.** CA
19bc0 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65  PI3REF: Convenie
19bd0 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72  nce Routines For
19be0 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73   Running Queries
19bf0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  .**.** This is a
19c00 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
19c10 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72  e that is preser
19c20 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ved for backward
19c30 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
19c40 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20  .** Use of this 
19c50 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
19c60 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a   recommended..**
19c70 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20  .** Definition: 
19c80 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c  A <b>result tabl
19c90 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20  e</b> is memory 
19ca0 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63  data structure c
19cb0 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a  reated by the.**
19cc0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
19cd0 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ble()] interface
19ce0 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  .  A result tabl
19cf0 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a  e records the.**
19d00 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20   complete query 
19d10 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65  results from one
19d20 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73   or more queries
19d30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ..**.** The tabl
19d40 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68  e conceptually h
19d50 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72  as a number of r
19d60 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e  ows and columns.
19d70 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e    But.** these n
19d80 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70  umbers are not p
19d90 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c  art of the resul
19da0 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20  t table itself. 
19db0 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72   These.** number
19dc0 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73  s are obtained s
19dd0 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20  eparately.  Let 
19de0 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  N be the number 
19df0 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d  of rows.** and M
19e00 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
19e10 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a  f columns..**.**
19e20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
19e30 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
19e40 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d  ointers to zero-
19e50 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
19e60 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65   strings..** The
19e70 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65  re are (N+1)*M e
19e80 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61  lements in the a
19e90 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74  rray.  The first
19ea0 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e   M pointers poin
19eb0 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72  t.** to zero-ter
19ec0 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
19ed0 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68  that  contain th
19ee0 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63  e names of the c
19ef0 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72  olumns..** The r
19f00 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73  emaining entries
19f10 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75   all point to qu
19f20 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55  ery results.  NU
19f30 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74  LL values result
19f40 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e  .** in NULL poin
19f50 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72  ters.  All other
19f60 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74   values are in t
19f70 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d  heir UTF-8 zero-
19f80 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
19f90 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74  ring representat
19fa0 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20  ion as returned 
19fb0 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
19fc0 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a  mn_text()]..**.*
19fd0 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
19fe0 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f   might consist o
19ff0 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65  f one or more me
1a000 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
1a010 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  ..** It is not s
1a020 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65  afe to pass a re
1a030 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63  sult table direc
1a040 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  tly to [sqlite3_
1a050 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65  free()]..** A re
1a060 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c  sult table shoul
1a070 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  d be deallocated
1a080 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1a090 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a  free_table()]..*
1a0a0 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61  *.** ^(As an exa
1a0b0 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75  mple of the resu
1a0c0 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c  lt table format,
1a0d0 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79   suppose a query
1a0e0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73   result.** is as
1a0f0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1a100 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1a110 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65  >.**        Name
1a120 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a          | Age.**
1a130 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d          --------
1a140 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
1a150 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20  **        Alice 
1a160 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20        | 43.**   
1a170 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20       Bob        
1a180 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20   | 28.**        
1a190 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31  Cindy       | 21
1a1a0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1a1b0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1a1c0 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75  ere are two colu
1a1d0 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68  mn (M==2) and th
1a1e0 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e  ree rows (N==3).
1a1f0 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65    Thus the.** re
1a200 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38  sult table has 8
1a210 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f   entries.  Suppo
1a220 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  se the result ta
1a230 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a  ble is stored.**
1a240 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d   in an array nam
1a250 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68  es azResult.  Th
1a260 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64  en azResult hold
1a270 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a  s this content:.
1a280 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1a290 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
1a2a0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30    azResult&#91;0
1a2b0 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20  ] = "Name";.**  
1a2c0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1a2d0 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a  91;1] = "Age";.*
1a2e0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1a2f0 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63  t&#91;2] = "Alic
1a300 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1a310 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20  Result&#91;3] = 
1a320 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "43";.**        
1a330 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20  azResult&#91;4] 
1a340 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20  = "Bob";.**     
1a350 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1a360 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20  5] = "28";.**   
1a370 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1a380 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a  1;6] = "Cindy";.
1a390 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1a3a0 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22  lt&#91;7] = "21"
1a3b0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1a3c0 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
1a3d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
1a3e0 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69  t_table() functi
1a3f0 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65  on evaluates one
1a400 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69   or more.** semi
1a410 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20  colon-separated 
1a420 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
1a430 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  n the zero-termi
1a440 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73  nated UTF-8.** s
1a450 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64  tring of its 2nd
1a460 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
1a470 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20  eturns a result 
1a480 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20  table to the.** 
1a490 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e  pointer given in
1a4a0 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74   its 3rd paramet
1a4b0 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  er..**.** After 
1a4c0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1a4d0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
1a4e0 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  h the result fro
1a4f0 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  m sqlite3_get_ta
1a500 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73  ble(),.** it mus
1a510 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c  t pass the resul
1a520 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20  t table pointer 
1a530 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  to sqlite3_free_
1a540 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72  table() in order
1a550 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74   to.** release t
1a560 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77  he memory that w
1a570 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65  as malloced.  Be
1a580 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79  cause of the way
1a590 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1a5a0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65  _malloc()] happe
1a5b0 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65  ns within sqlite
1a5c0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74  3_get_table(), t
1a5d0 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75  he calling.** fu
1a5e0 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  nction must not 
1a5f0 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c  try to call [sql
1a600 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72  ite3_free()] dir
1a610 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20  ectly.  Only.** 
1a620 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
1a630 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74  ble()] is able t
1a640 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  o release the me
1a650 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e  mory properly an
1a660 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  d safely..**.** 
1a670 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1a680 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  table() interfac
1a690 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
1a6a0 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72   as a wrapper ar
1a6b0 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
1a6c0 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73  _exec()].  The s
1a6d0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1a6e0 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
1a6f0 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a  not have access.
1a700 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e  ** to any intern
1a710 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72  al data structur
1a720 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49  es of SQLite.  I
1a730 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20  t uses only the 
1a740 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66  public.** interf
1a750 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65  ace defined here
1a760 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65  .  As a conseque
1a770 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74  nce, errors that
1a780 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a   occur in the.**
1a790 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f   wrapper layer o
1a7a0 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e  utside of the in
1a7b0 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f  ternal [sqlite3_
1a7c0 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65  exec()] call are
1a7d0 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65   not.** reflecte
1a7e0 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  d in subsequent 
1a7f0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
1a800 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a  3_errcode()] or.
1a810 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
1a820 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  sg()]..*/.int sq
1a830 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1a840 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1a850 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f           /* An o
1a860 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  pen database */.
1a870 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
1a880 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74  ql,     /* SQL t
1a890 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
1a8a0 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52  /.  char ***pazR
1a8b0 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73  esult,    /* Res
1a8c0 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72  ults of the quer
1a8d0 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f  y */.  int *pnRo
1a8e0 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  w,           /* 
1a8f0 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
1a900 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65   rows written he
1a910 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43  re */.  int *pnC
1a920 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a  olumn,        /*
1a930 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
1a940 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65  t columns writte
1a950 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72  n here */.  char
1a960 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20   **pzErrmsg     
1a970 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
1a980 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
1a990 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
1a9a0 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a  ree_table(char *
1a9b0 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a  *result);../*.**
1a9c0 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61   CAPI3REF: Forma
1a9d0 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e  tted String Prin
1a9e0 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ting Functions.*
1a9f0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1aa00 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69  nes are work-ali
1aa10 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e  kes of the "prin
1aa20 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20  tf()" family of 
1aa30 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f  functions.** fro
1aa40 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
1aa50 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20   library..**.** 
1aa60 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72  ^The sqlite3_mpr
1aa70 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
1aa80 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f  e3_vmprintf() ro
1aa90 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65  utines write the
1aaa0 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ir.** results in
1aab0 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
1aac0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
1aad0 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54  _malloc()]..** T
1aae0 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
1aaf0 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
1ab00 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
1ab10 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
1ab20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
1ab30 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74  ()].  ^Both rout
1ab40 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a  ines return a.**
1ab50 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
1ab60 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1ab70 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ()] is unable to
1ab80 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68   allocate enough
1ab90 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** memory to ho
1aba0 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  ld the resulting
1abb0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e   string..**.** ^
1abc0 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70  (The sqlite3_snp
1abd0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
1abe0 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73  is similar to "s
1abf0 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a  nprintf()" from.
1ac00 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  ** the standard 
1ac10 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  C library.  The 
1ac20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65  result is writte
1ac30 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75  n into the.** bu
1ac40 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73  ffer supplied as
1ac50 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1ac60 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65  meter whose size
1ac70 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20   is given by.** 
1ac80 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
1ac90 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74  ter. Note that t
1aca0 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a  he order of the.
1acb0 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72  ** first two par
1acc0 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72  ameters is rever
1acd0 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74  sed from snprint
1ace0 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20  f().)^  This is 
1acf0 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c  an.** historical
1ad00 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63   accident that c
1ad10 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77  annot be fixed w
1ad20 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a  ithout breaking.
1ad30 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
1ad40 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e  patibility.  ^(N
1ad50 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71  ote also that sq
1ad60 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1ad70 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f  .** returns a po
1ad80 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66  inter to its buf
1ad90 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74  fer instead of t
1ada0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
1adb0 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61  characters actua
1adc0 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  lly written into
1add0 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20   the buffer.)^  
1ade0 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a  We admit that.**
1adf0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1ae00 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65  haracters writte
1ae10 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72  n would be a mor
1ae20 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a  e useful return.
1ae30 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20  ** value but we 
1ae40 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  cannot change th
1ae50 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
1ae60 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
1ae70 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69  intf().** now wi
1ae80 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63  thout breaking c
1ae90 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
1aea0 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20  .** ^As long as 
1aeb0 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20  the buffer size 
1aec0 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  is greater than 
1aed0 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e  zero, sqlite3_sn
1aee0 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72  printf().** guar
1aef0 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
1af00 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73  buffer is always
1af10 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1af20 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a  .  ^The first.**
1af30 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69   parameter "n" i
1af40 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65  s the total size
1af50 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20   of the buffer, 
1af60 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20  including space 
1af70 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20  for.** the zero 
1af80 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20  terminator.  So 
1af90 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69  the longest stri
1afa0 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63  ng that can be c
1afb0 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69  ompletely.** wri
1afc0 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31  tten will be n-1
1afd0 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
1afe0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1aff0 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  vsnprintf() rout
1b000 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73  ine is a varargs
1b010 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69   version of sqli
1b020 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a  te3_snprintf()..
1b030 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1b040 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  ines all impleme
1b050 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  nt some addition
1b060 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a  al formatting.**
1b070 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72   options that ar
1b080 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e  e useful for con
1b090 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74  structing SQL st
1b0a0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c  atements..** All
1b0b0 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72   of the usual pr
1b0c0 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e  intf() formattin
1b0d0 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e  g options apply.
1b0e0 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74    In addition, t
1b0f0 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22  here.** is are "
1b100 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22  %q", "%Q", and "
1b110 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a  %z" options..**.
1b120 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69  ** ^(The %q opti
1b130 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73  on works like %s
1b140 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73   in that it subs
1b150 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65  titutes a nul-te
1b160 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
1b170 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75  ng from the argu
1b180 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20  ment list.  But 
1b190 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20  %q also doubles 
1b1a0 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61  every '\'' chara
1b1b0 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64  cter..** %q is d
1b1c0 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20  esigned for use 
1b1d0 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20  inside a string 
1b1e0 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64  literal.)^  By d
1b1f0 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27  oubling each '\'
1b200 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69  '.** character i
1b210 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63  t escapes that c
1b220 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c  haracter and all
1b230 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73  ows it to be ins
1b240 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  erted into.** th
1b250 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  e string..**.** 
1b260 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73  For example, ass
1b270 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76  ume the string v
1b280 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f  ariable zText co
1b290 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66  ntains text as f
1b2a0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1b2b0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1b2c0 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20  **  char *zText 
1b2d0 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20  = "It's a happy 
1b2e0 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  day!";.** </pre>
1b2f0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1b300 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20  .** One can use 
1b310 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20  this text in an 
1b320 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
1b330 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1b340 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1b350 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
1b360 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
1b370 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
1b380 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71  table VALUES('%q
1b390 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  ')", zText);.** 
1b3a0 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
1b3b0 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
1b3c0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
1b3d0 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
1b3e0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1b3f0 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
1b400 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72  he %q format str
1b410 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
1b420 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20   '\'' character 
1b430 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65  in zText.** is e
1b440 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53  scaped and the S
1b450 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20  QL generated is 
1b460 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1b470 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1b480 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
1b490 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
1b4a0 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79  S('It''s a happy
1b4b0 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65   day!').** </pre
1b4c0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1b4d0 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72  *.** This is cor
1b4e0 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73  rect.  Had we us
1b4f0 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66  ed %s instead of
1b500 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74   %q, the generat
1b510 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20  ed SQL.** would 
1b520 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65  have looked like
1b530 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c   this:.**.** <bl
1b540 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1b550 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
1b560 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
1b570 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
1b580 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1b590 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1b5a0 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d  This second exam
1b5b0 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79  ple is an SQL sy
1b5c0 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20  ntax error.  As 
1b5d0 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79  a general rule y
1b5e0 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77  ou should.** alw
1b5f0 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65  ays use %q inste
1b600 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e  ad of %s when in
1b610 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74  serting text int
1b620 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  o a string liter
1b630 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  al..**.** ^(The 
1b640 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %Q option works 
1b650 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69  like %q except i
1b660 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67  t also adds sing
1b670 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64  le quotes around
1b680 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20  .** the outside 
1b690 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72  of the total str
1b6a0 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ing.  Additional
1b6b0 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d  ly, if the param
1b6c0 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61  eter in the.** a
1b6d0 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20  rgument list is 
1b6e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
1b6f0 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74  %Q substitutes t
1b700 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28  he text "NULL" (
1b710 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c  without.** singl
1b720 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f  e quotes).)^  So
1b730 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f  , for example, o
1b740 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a  ne could say:.**
1b750 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1b760 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
1b770 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
1b780 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
1b790 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
1b7a0 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  (%Q)", zText);.*
1b7b0 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
1b7c0 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
1b7d0 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
1b7e0 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
1b7f0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1b800 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  e>.**.** The cod
1b810 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e  e above will ren
1b820 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51  der a correct SQ
1b830 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  L statement in t
1b840 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61  he zSQL.** varia
1b850 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20  ble even if the 
1b860 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69  zText variable i
1b870 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1b880 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25  ..**.** ^(The "%
1b890 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  z" formatting op
1b8a0 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1b8b0 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68  "%s" but with th
1b8c0 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68  e.** addition th
1b8d0 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72  at after the str
1b8e0 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61  ing has been rea
1b8f0 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74  d and copied int
1b900 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c  o.** the result,
1b910 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1b920 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74  ] is called on t
1b930 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e  he input string.
1b940 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69  )^.*/.char *sqli
1b950 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73  te3_mprintf(cons
1b960 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68  t char*,...);.ch
1b970 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72  ar *sqlite3_vmpr
1b980 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
1b990 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72  , va_list);.char
1b9a0 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   *sqlite3_snprin
1b9b0 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e  tf(int,char*,con
1b9c0 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a  st char*, ...);.
1b9d0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73  char *sqlite3_vs
1b9e0 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1b9f0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  *,const char*, v
1ba00 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  a_list);../*.** 
1ba10 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
1ba20 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73   Allocation Subs
1ba30 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ystem.**.** The 
1ba40 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
1ba50 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75   these three rou
1ba60 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66  tines for all of
1ba70 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65   its own.** inte
1ba80 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rnal memory allo
1ba90 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43  cation needs. "C
1baa0 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76  ore" in the prev
1bab0 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a  ious sentence.**
1bac0 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
1bad0 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  e operating-syst
1bae0 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20  em specific VFS 
1baf0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
1bb00 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20   The.** Windows 
1bb10 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20  VFS uses native 
1bb20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
1bb30 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65  e() for some ope
1bb40 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  rations..**.** ^
1bb50 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  The sqlite3_mall
1bb60 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  oc() routine ret
1bb70 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1bb80 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20  o a block.** of 
1bb90 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20  memory at least 
1bba0 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74  N bytes in lengt
1bbb0 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  h, where N is th
1bbc0 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
1bbd0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
1bbe0 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  oc() is unable t
1bbf0 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69  o obtain suffici
1bc00 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f  ent free.** memo
1bc10 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61  ry, it returns a
1bc20 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
1bc30 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65  ^If the paramete
1bc40 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  r N to.** sqlite
1bc50 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  3_malloc() is ze
1bc60 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  ro or negative t
1bc70 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  hen sqlite3_mall
1bc80 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  oc() returns.** 
1bc90 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1bca0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  **.** ^Calling s
1bcb0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69  qlite3_free() wi
1bcc0 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65  th a pointer pre
1bcd0 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
1bce0 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  .** by sqlite3_m
1bcf0 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1bd00 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c  e3_realloc() rel
1bd10 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72  eases that memor
1bd20 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20  y so.** that it 
1bd30 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e  might be reused.
1bd40 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66    ^The sqlite3_f
1bd50 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ree() routine is
1bd60 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69  .** a no-op if i
1bd70 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
1bd80 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50  NULL pointer.  P
1bd90 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f  assing a NULL po
1bda0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69  inter.** to sqli
1bdb0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61  te3_free() is ha
1bdc0 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62  rmless.  After b
1bdd0 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f  eing freed, memo
1bde0 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69  ry.** should nei
1bdf0 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72  ther be read nor
1be00 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20   written.  Even 
1be10 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73  reading previous
1be20 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f  ly freed.** memo
1be30 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ry might result 
1be40 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  in a segmentatio
1be50 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72  n fault or other
1be60 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a   severe error..*
1be70 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74  * Memory corrupt
1be80 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74  ion, a segmentat
1be90 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74  ion fault, or ot
1bea0 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
1beb0 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74  .** might result
1bec0 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65   if sqlite3_free
1bed0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  () is called wit
1bee0 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  h a non-NULL poi
1bef0 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73  nter that.** was
1bf00 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72   not obtained fr
1bf10 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
1bf20 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
1bf30 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20  ealloc()..**.** 
1bf40 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  ^(The sqlite3_re
1bf50 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63  alloc() interfac
1bf60 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  e attempts to re
1bf70 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20  size a.** prior 
1bf80 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1bf90 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74  n to be at least
1bfa0 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20   N bytes, where 
1bfb0 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f  N is the.** seco
1bfc0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
1bfd0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
1bfe0 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a  tion to be resiz
1bff0 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  ed is the first.
1c000 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29 5e 20  ** parameter.)^ 
1c010 5e 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70  ^ If the first p
1c020 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1c030 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
1c040 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1c050 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61  er then its beha
1c060 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61  vior is identica
1c070 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  l to calling.** 
1c080 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
1c090 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  ) where N is the
1c0a0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1c0b0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
1c0c0 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74  lloc()..** ^If t
1c0d0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1c0e0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1c0f0 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  ealloc() is zero
1c100 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20   or.** negative 
1c110 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
1c120 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65  r is exactly the
1c130 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67   same as calling
1c140 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65  .** sqlite3_free
1c150 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74  (P) where P is t
1c160 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1c170 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
1c180 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c  alloc()..** ^sql
1c190 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
1c1a0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1c1b0 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   to a memory all
1c1c0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74  ocation.** of at
1c1d0 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
1c1e0 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69  n size or NULL i
1c1f0 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  f sufficient mem
1c200 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62  ory is unavailab
1c210 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20  le..** ^If M is 
1c220 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
1c230 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1c240 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20  , then min(N,M) 
1c250 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20  bytes.** of the 
1c260 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1c270 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f   are copied into
1c280 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
1c290 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65  f buffer returne
1c2a0 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
1c2b0 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68  realloc() and th
1c2c0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1c2d0 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20  on is freed..** 
1c2e0 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  ^If sqlite3_real
1c2f0 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55  loc() returns NU
1c300 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69  LL, then the pri
1c310 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  or allocation.**
1c320 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a   is not freed..*
1c330 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
1c340 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1c350 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e  ite3_malloc() an
1c360 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  d sqlite3_reallo
1c370 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  c().** is always
1c380 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c   aligned to at l
1c390 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62  east an 8 byte b
1c3a0 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61  oundary, or to a
1c3b0 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64  .** 4 byte bound
1c3c0 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49  ary if the [SQLI
1c3d0 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45  TE_4_BYTE_ALIGNE
1c3e0 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c  D_MALLOC] compil
1c3f0 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
1c400 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
1c410 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  In SQLite versio
1c420 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e  n 3.5.0 and 3.5.
1c430 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62  1, it was possib
1c440 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20  le to define.** 
1c450 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  the SQLITE_OMIT_
1c460 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f  MEMORY_ALLOCATIO
1c470 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61  N which would ca
1c480 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  use the built-in
1c490 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
1c4a0 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  on of these rout
1c4b0 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74  ines to be omitt
1c4c0 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69  ed.  That capabi
1c4d0 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f  lity.** is no lo
1c4e0 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20  nger provided.  
1c4f0 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65  Only built-in me
1c500 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20  mory allocators 
1c510 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a  can be used..**.
1c520 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69  ** Prior to SQLi
1c530 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31  te version 3.7.1
1c540 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20 4f  0, the Windows O
1c550 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
1c560 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20  r called.** the 
1c570 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
1c580 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63  and free() direc
1c590 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74  tly when convert
1c5a0 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73  ing.** filenames
1c5b0 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46   between the UTF
1c5c0 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  -8 encoding used
1c5d0 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e   by SQLite.** an
1c5e0 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e  d whatever filen
1c5f0 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ame encoding is 
1c600 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74  used by the part
1c610 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a  icular Windows.*
1c620 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20  * installation. 
1c630 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
1c640 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20 64  on errors were d
1c650 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20  etected, but.** 
1c660 74 68 65 79 20 77 65 72 65 20 72 65 70 6f 72 74  they were report
1c670 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49  ed back as [SQLI
1c680 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a  TE_CANTOPEN] or.
1c690 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ** [SQLITE_IOERR
1c6a0 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53  ] rather than [S
1c6b0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
1c6c0 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20  .** The pointer 
1c6d0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71  arguments to [sq
1c6e0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e  lite3_free()] an
1c6f0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
1c700 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65  oc()].** must be
1c710 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20   either NULL or 
1c720 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62  else pointers ob
1c730 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72  tained from a pr
1c740 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ior.** invocatio
1c750 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
1c760 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  lloc()] or [sqli
1c770 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74  te3_realloc()] t
1c780 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20  hat have.** not 
1c790 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65  yet been release
1c7a0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  d..**.** The app
1c7b0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
1c7c0 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20  t read or write 
1c7d0 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61  any part of.** a
1c7e0 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
1c7f0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
1c800 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e  en released usin
1c810 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  g.** [sqlite3_fr
1c820 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ee()] or [sqlite
1c830 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  3_realloc()]..*/
1c840 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d  .void *sqlite3_m
1c850 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64  alloc(int);.void
1c860 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   *sqlite3_reallo
1c870 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76  c(void*, int);.v
1c880 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
1c890 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  (void*);../*.** 
1c8a0 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
1c8b0 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69   Allocator Stati
1c8c0 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  stics.**.** SQLi
1c8d0 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73  te provides thes
1c8e0 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73  e two interfaces
1c8f0 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f   for reporting o
1c900 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20  n the status.** 
1c910 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
1c920 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69  malloc()], [sqli
1c930 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64  te3_free()], and
1c940 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1c950 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  c()].** routines
1c960 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65  , which form the
1c970 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
1c980 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
1c990 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ystem..**.** ^Th
1c9a0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
1c9b0 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e  y_used()] routin
1c9c0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
1c9d0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a  mber of bytes.**
1c9e0 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65   of memory curre
1c9f0 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67  ntly outstanding
1ca00 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e   (malloced but n
1ca10 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54  ot freed)..** ^T
1ca20 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
1ca30 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1ca40 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1ca50 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76  the maximum.** v
1ca60 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
1ca70 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1ca80 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77  since the high-w
1ca90 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73  ater mark.** was
1caa0 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54   last reset.  ^T
1cab0 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
1cac0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ed by [sqlite3_m
1cad0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e  emory_used()] an
1cae0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d.** [sqlite3_me
1caf0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1cb00 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76  ] include any ov
1cb10 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20  erhead.** added 
1cb20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73  by SQLite in its
1cb30 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1cb40 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
1cb50 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f  oc()],.** but no
1cb60 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64  t overhead added
1cb70 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65   by the any unde
1cb80 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69  rlying system li
1cb90 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65  brary.** routine
1cba0 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  s that [sqlite3_
1cbb0 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61  malloc()] may ca
1cbc0 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ll..**.** ^The m
1cbd0 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72  emory high-water
1cbe0 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74   mark is reset t
1cbf0 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  o the current va
1cc00 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74  lue of.** [sqlit
1cc10 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1cc20 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  ] if and only if
1cc30 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74   the parameter t
1cc40 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  o.** [sqlite3_me
1cc50 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1cc60 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65  ] is true.  ^The
1cc70 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
1cc80 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ** by [sqlite3_m
1cc90 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1cca0 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d  1)] is the high-
1ccb0 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72  water mark.** pr
1ccc0 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74  ior to the reset
1ccd0 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
1cce0 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
1ccf0 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71  y_used(void);.sq
1cd00 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
1cd10 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1cd20 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c  ater(int resetFl
1cd30 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ag);../*.** CAPI
1cd40 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e  3REF: Pseudo-Ran
1cd50 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72  dom Number Gener
1cd60 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ator.**.** SQLit
1cd70 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67  e contains a hig
1cd80 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f  h-quality pseudo
1cd90 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67  -random number g
1cda0 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20  enerator (PRNG) 
1cdb0 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63  used to.** selec
1cdc0 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20  t random [ROWID 
1cdd0 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69  | ROWIDs] when i
1cde0 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63  nserting new rec
1cdf0 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c  ords into a tabl
1ce00 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64  e that.** alread
1ce10 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65  y uses the large
1ce20 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57  st possible [ROW
1ce30 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69  ID].  The PRNG i
1ce40 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a  s also used for.
1ce50 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20  ** the build-in 
1ce60 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e  random() and ran
1ce70 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75  domblob() SQL fu
1ce80 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69  nctions.  This i
1ce90 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a  nterface allows.
1cea0 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
1ceb0 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61  to access the sa
1cec0 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65  me PRNG for othe
1ced0 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a  r purposes..**.*
1cee0 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69  * ^A call to thi
1cef0 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
1cf00 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64   N bytes of rand
1cf10 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66  omness into buff
1cf20 65 72 20 50 2e 0a 2a 2a 20 5e 49 66 20 4e 20 69  er P..** ^If N i
1cf30 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 2c  s less than one,
1cf40 20 74 68 65 6e 20 50 20 63 61 6e 20 62 65 20 61   then P can be a
1cf50 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1cf60 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72 6f  *.** ^If this ro
1cf70 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62 65  utine has not be
1cf80 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63 61  en previously ca
1cf90 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20 70  lled or if the p
1cfa0 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20  revious.** call 
1cfb0 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e 20  had N less than 
1cfc0 6f 6e 65 2c 20 74 68 65 6e 20 74 68 65 20 50 52  one, then the PR
1cfd0 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 73 69  NG is seeded usi
1cfe0 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a  ng randomness.**
1cff0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74   obtained from t
1d000 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d  he xRandomness m
1d010 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
1d020 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
1d030 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49  s] object..** ^I
1d040 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  f the previous c
1d050 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74  all to this rout
1d060 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f 66 20  ine had an N of 
1d070 31 20 6f 72 20 6d 6f 72 65 20 74 68 65 6e 0a 2a  1 or more then.*
1d080 2a 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e  * the pseudo-ran
1d090 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72  domness is gener
1d0a0 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c  ated.** internal
1d0b0 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72  ly and without r
1d0c0 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b  ecourse to the [
1d0d0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61  sqlite3_vfs] xRa
1d0e0 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68  ndomness.** meth
1d0f0 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  od..*/.void sqli
1d100 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69  te3_randomness(i
1d110 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a  nt N, void *P);.
1d120 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1d130 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75   Compile-Time Au
1d140 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c  thorization Call
1d150 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  backs.**.** ^Thi
1d160 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74  s routine regist
1d170 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ers an authorize
1d180 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20  r callback with 
1d190 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
1d1a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1d1b0 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20  tion], supplied 
1d1c0 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
1d1d0 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61  ument..** ^The a
1d1e0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1d1f0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73  ck is invoked as
1d200 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1d210 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c  are being compil
1d220 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
1d230 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
1d240 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71  its variants [sq
1d250 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1d260 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
1d270 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e  _prepare16()] an
1d280 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
1d290 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74  re16_v2()].  ^At
1d2a0 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e   various.** poin
1d2b0 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f  ts during the co
1d2c0 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73  mpilation proces
1d2d0 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62  s, as logic is b
1d2e0 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20  eing created.** 
1d2f0 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
1d300 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20  us actions, the 
1d310 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1d320 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  ack is invoked t
1d330 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73  o.** see if thos
1d340 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c  e actions are al
1d350 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74  lowed.  ^The aut
1d360 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1d370 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
1d380 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f  n [SQLITE_OK] to
1d390 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f   allow the actio
1d3a0 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  n, [SQLITE_IGNOR
1d3b0 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74  E] to disallow t
1d3c0 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61  he.** specific a
1d3d0 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20  ction but allow 
1d3e0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1d3f0 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f  t to continue to
1d400 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c   be.** compiled,
1d410 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
1d420 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65  ] to cause the e
1d430 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d  ntire SQL statem
1d440 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a  ent to be.** rej
1d450 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72  ected with an er
1d460 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75  ror.  ^If the au
1d470 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1d480 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  k returns.** any
1d490 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
1d4a0 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  n [SQLITE_IGNORE
1d4b0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ], [SQLITE_OK], 
1d4c0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
1d4d0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71  .** then the [sq
1d4e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1d4f0 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
1d500 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
1d510 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74  gered.** the aut
1d520 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
1d530 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
1d540 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57  message..**.** W
1d550 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
1d560 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1d570 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  _OK], that means
1d580 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
1d590 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f  * requested is o
1d5a0 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61  k.  ^When the ca
1d5b0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
1d5c0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68  SQLITE_DENY], th
1d5d0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
1d5e0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
1d5f0 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
1d600 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
1d610 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
1d620 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
1d630 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
1d640 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a  explaining that.
1d650 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e  ** access is den
1d660 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ied. .**.** ^The
1d670 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1d680 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
1d690 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
1d6a0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
1d6b0 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
1d6c0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  to the sqlite3_s
1d6d0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20  et_authorizer() 
1d6e0 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20  interface. ^The 
1d6f0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1d700 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
1d710 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
1d720 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c  r [SQLITE_COPY |
1d730 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68   action code] th
1d740 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
1d750 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61  the particular a
1d760 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
1d770 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69  orized. ^The thi
1d780 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68  rd through sixth
1d790 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
1d7a0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
1d7b0 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  re zero-terminat
1d7c0 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
1d7d0 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e  contain addition
1d7e0 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62  al.** details ab
1d7f0 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74  out the action t
1d800 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
1d810 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  .**.** ^If the a
1d820 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
1d830 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61  QLITE_READ].** a
1d840 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
1d850 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1d860 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
1d870 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
1d880 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65  atement] stateme
1d890 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65  nt is constructe
1d8a0 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a  d to substitute.
1d8b0 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20  ** a NULL value 
1d8c0 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
1d8d0 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
1d8e0 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20  t would have.** 
1d8f0 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51  been read if [SQ
1d900 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65  LITE_OK] had bee
1d910 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  n returned.  The
1d920 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1d930 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62  .** return can b
1d940 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61  e used to deny a
1d950 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72  n untrusted user
1d960 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76   access to indiv
1d970 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73  idual.** columns
1d980 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20   of a table..** 
1d990 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
1d9a0 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44  ode is [SQLITE_D
1d9b0 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63  ELETE] and the c
1d9c0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
1d9d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ** [SQLITE_IGNOR
1d9e0 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c  E] then the [DEL
1d9f0 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70  ETE] operation p
1da00 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a  roceeds but the.
1da10 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74  ** [truncate opt
1da20 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69  imization] is di
1da30 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72  sabled and all r
1da40 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ows are deleted 
1da50 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a  individually..**
1da60 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  .** An authorize
1da70 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b  r is used when [
1da80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
1da90 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20  | preparing].** 
1daa0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66  SQL statements f
1dab0 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64  rom an untrusted
1dac0 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75   source, to ensu
1dad0 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  re that the SQL 
1dae0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f  statements.** do
1daf0 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65   not try to acce
1db00 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65  ss data they are
1db10 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20   not allowed to 
1db20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65  see, or that the
1db30 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20  y do not.** try 
1db40 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63  to execute malic
1db50 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20  ious statements 
1db60 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20  that damage the 
1db70 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a  database.  For.*
1db80 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  * example, an ap
1db90 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c  plication may al
1dba0 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e  low a user to en
1dbb0 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a  ter arbitrary.**
1dbc0 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72   SQL queries for
1dbd0 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61   evaluation by a
1dbe0 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20   database.  But 
1dbf0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1dc00 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74  does.** not want
1dc10 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20   the user to be 
1dc20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62  able to make arb
1dc30 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74  itrary changes t
1dc40 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  o the.** databas
1dc50 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  e.  An authorize
1dc60 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20  r could then be 
1dc70 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69  put in place whi
1dc80 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65  le the.** user-e
1dc90 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65  ntered SQL is be
1dca0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
1dcb0 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d  pare | prepared]
1dcc0 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f   that.** disallo
1dcd0 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78  ws everything ex
1dce0 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74  cept [SELECT] st
1dcf0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
1dd00 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
1dd10 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73  t need to proces
1dd20 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75  s SQL from untru
1dd30 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20  sted sources.** 
1dd40 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69  might also consi
1dd50 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73  der lowering res
1dd60 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69  ource limits usi
1dd70 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
1dd80 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69  t()].** and limi
1dd90 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69  ting database si
1dda0 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61  ze using the [ma
1ddb0 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
1ddc0 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64  RAGMA].** in add
1ddd0 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61  ition to using a
1dde0 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a  n authorizer..**
1ddf0 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e  .** ^(Only a sin
1de00 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  gle authorizer c
1de10 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f  an be in place o
1de20 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  n a database con
1de30 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20  nection.** at a 
1de40 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c  time.  Each call
1de50 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
1de60 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72  authorizer overr
1de70 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76  ides the.** prev
1de80 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44  ious call.)^  ^D
1de90 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f  isable the autho
1dea0 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c  rizer by install
1deb0 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62  ing a NULL callb
1dec0 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ack..** The auth
1ded0 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c  orizer is disabl
1dee0 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
1def0 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  *.** The authori
1df00 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  zer callback mus
1df10 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
1df20 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
1df30 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
1df40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
1df50 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61  at invoked the a
1df60 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1df70 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ck..** Note that
1df80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1df90 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
1dfa0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
1dfb0 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
1dfc0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1dfd0 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
1dfe0 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
1dff0 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
1e000 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  raph..**.** ^Whe
1e010 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
1e020 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64  re_v2()] is used
1e030 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74   to prepare a st
1e040 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20  atement, the.** 
1e050 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20  statement might 
1e060 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64  be re-prepared d
1e070 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  uring [sqlite3_s
1e080 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20  tep()] due to a 
1e090 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67  .** schema chang
1e0a0 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61  e.  Hence, the a
1e0b0 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
1e0c0 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  d ensure that th
1e0d0 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74  e.** correct aut
1e0e0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1e0f0 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63   remains in plac
1e100 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71  e during the [sq
1e110 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
1e120 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20  *.** ^Note that 
1e130 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1e140 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1e150 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a  ed only during.*
1e160 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1e170 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
1e180 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a  iants.  Authoriz
1e190 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20  ation is not.** 
1e1a0 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67  performed during
1e1b0 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75   statement evalu
1e1c0 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65  ation in [sqlite
1e1d0 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73  3_step()], unles
1e1e0 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69  s.** as stated i
1e1f0 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70  n the previous p
1e200 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65  aragraph, sqlite
1e210 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73  3_step() invokes
1e220 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70  .** sqlite3_prep
1e230 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72  are_v2() to repr
1e240 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
1e250 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61  t after a schema
1e260 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20   change..*/.int 
1e270 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1e280 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65  orizer(.  sqlite
1e290 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74  3*,.  int (*xAut
1e2a0 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  h)(void*,int,con
1e2b0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
1e2c0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1e2d0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20  ,const char*),. 
1e2e0 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61   void *pUserData
1e2f0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
1e300 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
1e310 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Return Codes.**.
1e320 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
1e330 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
1e340 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1e350 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d  back function] m
1e360 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69  ust.** return ei
1e370 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ther [SQLITE_OK]
1e380 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   or one of these
1e390 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69   two constants i
1e3a0 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69  n order.** to si
1e3b0 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74  gnal SQLite whet
1e3c0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61  her or not the a
1e3d0 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
1e3e0 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  ed.  See the.** 
1e3f0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1e400 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
1e410 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69  izer documentati
1e420 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  on] for addition
1e430 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
1e440 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  n..**.** Note th
1e450 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  at SQLITE_IGNORE
1e460 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73   is also used as
1e470 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73   a [conflict res
1e480 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a  olution mode].**
1e490 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74   returned from t
1e4a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  he [sqlite3_vtab
1e4b0 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
1e4c0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64  interface..*/.#d
1e4d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e  efine SQLITE_DEN
1e4e0 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74  Y   1   /* Abort
1e4f0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1e500 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  nt with an error
1e510 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e520 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a  TE_IGNORE 2   /*
1e530 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63   Don't allow acc
1e540 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67  ess, but don't g
1e550 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72  enerate an error
1e560 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
1e570 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
1e580 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Action Codes.**.
1e590 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
1e5a0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
1e5b0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
1e5c0 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
1e5d0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61   function.** tha
1e5e0 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20  t is invoked to 
1e5f0 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69  authorize certai
1e600 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
1e610 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a  actions.  The.**
1e620 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1e630 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
1e640 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
1e650 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66  code that specif
1e660 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69  ies.** what acti
1e670 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68  on is being auth
1e680 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61  orized.  These a
1e690 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61  re the integer a
1e6a0 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74  ction codes that
1e6b0 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
1e6c0 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20  er callback may 
1e6d0 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a  be passed..**.**
1e6e0 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f   These action co
1e6f0 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66  de values signif
1e700 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f  y what kind of o
1e710 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62  peration is to b
1e720 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e  e.** authorized.
1e730 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74    The 3rd and 4t
1e740 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
1e750 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f  the authorizatio
1e760 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75  n.** callback fu
1e770 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70  nction will be p
1e780 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c  arameters or NUL
1e790 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77  L depending on w
1e7a0 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a  hich of these.**
1e7b0 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61   codes is used a
1e7c0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
1e7d0 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35  ameter.  ^(The 5
1e7e0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
1e7f0 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
1e800 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
1e810 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
1e820 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20  tabase ("main", 
1e830 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29  "temp",.** etc.)
1e840 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29   if applicable.)
1e850 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61  ^  ^The 6th para
1e860 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
1e870 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1e880 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
1e890 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73  of the inner-mos
1e8a0 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65  t trigger or vie
1e8b0 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e  w that is respon
1e8c0 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65  sible for.** the
1e8d0 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
1e8e0 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20  or NULL if this 
1e8f0 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69  access attempt i
1e900 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a  s directly from.
1e910 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c  ** top-level SQL
1e920 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a   code..*/./*****
1e930 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e940 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e950 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a  ****** 3rd *****
1e960 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a  ******* 4th ****
1e970 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65  *******/.#define
1e980 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49   SQLITE_CREATE_I
1e990 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20  NDEX          1 
1e9a0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1e9b0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1e9c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1e9d0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41  SQLITE_CREATE_TA
1e9e0 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20  BLE          2  
1e9f0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1ea00 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1ea10 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1ea20 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1ea30 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20  P_INDEX     3   
1ea40 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1ea50 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1ea60 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1ea70 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1ea80 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f  _TABLE     4   /
1ea90 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1eaa0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1eab0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1eac0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1ead0 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a  TRIGGER   5   /*
1eae0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1eaf0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1eb00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1eb10 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56  TE_CREATE_TEMP_V
1eb20 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20  IEW      6   /* 
1eb30 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1eb40 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1eb50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1eb60 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52  E_CREATE_TRIGGER
1eb70 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54          7   /* T
1eb80 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
1eb90 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1eba0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ebb0 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20  _CREATE_VIEW    
1ebc0 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69         8   /* Vi
1ebd0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
1ebe0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1ebf0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ec00 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
1ec10 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62        9   /* Tab
1ec20 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1ec30 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1ec40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1ec50 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ROP_INDEX       
1ec60 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65      10   /* Inde
1ec70 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1ec80 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1ec90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1eca0 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  OP_TABLE        
1ecb0 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65     11   /* Table
1ecc0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1ecd0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1ece0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1ecf0 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  P_TEMP_INDEX    
1ed00 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20    12   /* Index 
1ed10 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1ed20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1ed30 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1ed40 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
1ed50 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   13   /* Table N
1ed60 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1ed70 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1ed80 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1ed90 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20  TEMP_TRIGGER    
1eda0 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  14   /* Trigger 
1edb0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1edc0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1edd0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1ede0 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31  EMP_VIEW       1
1edf0 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  5   /* View Name
1ee00 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1ee10 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1ee20 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52  e SQLITE_DROP_TR
1ee30 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36  IGGER         16
1ee40 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1ee50 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1ee60 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1ee70 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45   SQLITE_DROP_VIE
1ee80 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20  W            17 
1ee90 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1eea0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1eeb0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1eec0 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20  SQLITE_INSERT   
1eed0 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20              18  
1eee0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1eef0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1ef00 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1ef10 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20  QLITE_PRAGMA    
1ef20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20             19   
1ef30 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20  /* Pragma Name  
1ef40 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55     1st arg or NU
1ef50 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  LL */.#define SQ
1ef60 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20  LITE_READ       
1ef70 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f            20   /
1ef80 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1ef90 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
1efa0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1efb0 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20  ITE_SELECT      
1efc0 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a           21   /*
1efd0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1efe0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1eff0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f000 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20  TE_TRANSACTION  
1f010 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20          22   /* 
1f020 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
1f030 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f040 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f050 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20  E_UPDATE        
1f060 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54         23   /* T
1f070 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
1f080 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
1f090 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f0a0 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20  _ATTACH         
1f0b0 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69        24   /* Fi
1f0c0 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55  lename        NU
1f0d0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1f0e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f0f0 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20  DETACH          
1f100 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74       25   /* Dat
1f110 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c  abase Name   NUL
1f120 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1f130 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
1f140 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20  LTER_TABLE      
1f150 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61      26   /* Data
1f160 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c  base Name   Tabl
1f170 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1f180 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
1f190 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
1f1a0 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78     27   /* Index
1f1b0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1f1c0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1f1d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41  efine SQLITE_ANA
1f1e0 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  LYZE            
1f1f0 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    28   /* Table 
1f200 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1f210 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1f220 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1f230 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  TE_VTABLE       
1f240 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   29   /* Table N
1f250 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
1f260 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1f270 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1f280 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  VTABLE          
1f290 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  30   /* Table Na
1f2a0 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
1f2b0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
1f2c0 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49  ne SQLITE_FUNCTI
1f2d0 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33  ON             3
1f2e0 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
1f2f0 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20         Function 
1f300 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e  Name   */.#defin
1f310 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49  e SQLITE_SAVEPOI
1f320 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32  NT            32
1f330 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
1f340 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20        Savepoint 
1f350 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65  Name  */.#define
1f360 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20   SQLITE_COPY    
1f370 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20                0 
1f380 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75    /* No longer u
1f390 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  sed */.#define S
1f3a0 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45 20  QLITE_RECURSIVE 
1f3b0 20 20 20 20 20 20 20 20 20 20 20 33 33 20 20 20             33   
1f3c0 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
1f3d0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1f3e0 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     */../*.** CAP
1f3f0 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41  I3REF: Tracing A
1f400 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e  nd Profiling Fun
1f410 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
1f420 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
1f430 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
1f440 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
1f450 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
1f460 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
1f470 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
1f480 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
1f490 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
1f4a0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
1f4b0 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
1f4c0 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  y sqlite3_trace(
1f4d0 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a  ) is invoked at.
1f4e0 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73  ** various times
1f4f0 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61   when an SQL sta
1f500 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20  tement is being 
1f510 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  run by [sqlite3_
1f520 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  step()]..** ^The
1f530 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
1f540 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1f550 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d  oked with a UTF-
1f560 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  8 rendering of t
1f570 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  he.** SQL statem
1f580 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20  ent text as the 
1f590 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20  statement first 
1f5a0 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67  begins executing
1f5b0 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61  ..** ^(Additiona
1f5c0 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  l sqlite3_trace(
1f5d0 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68  ) callbacks migh
1f5e0 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61  t occur.** as ea
1f5f0 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62  ch triggered sub
1f600 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72  program is enter
1f610 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63  ed.  The callbac
1f620 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a  ks for triggers.
1f630 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46  ** contain a UTF
1f640 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74  -8 SQL comment t
1f650 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74  hat identifies t
1f660 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a  he trigger.)^.**
1f670 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
1f680 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54  TRACE_SIZE_LIMIT
1f690 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1f6a0 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
1f6b0 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68  d to limit.** th
1f6c0 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75  e length of [bou
1f6d0 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78  nd parameter] ex
1f6e0 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f  pansion in the o
1f6f0 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33  utput of sqlite3
1f700 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  _trace()..**.** 
1f710 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
1f720 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
1f730 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f  d by sqlite3_pro
1f740 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  file() is invoke
1f750 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c  d.** as each SQL
1f760 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
1f770 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  hes.  ^The profi
1f780 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  le callback cont
1f790 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67  ains.** the orig
1f7a0 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74  inal statement t
1f7b0 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d  ext and an estim
1f7c0 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63  ate of wall-cloc
1f7d0 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77  k time.** of how
1f7e0 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65   long that state
1f7f0 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e  ment took to run
1f800 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
1f810 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65  callback.** time
1f820 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20   is in units of 
1f830 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77  nanoseconds, how
1f840 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74  ever the current
1f850 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
1f860 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62  ** is only capab
1f870 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  le of millisecon
1f880 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20  d resolution so 
1f890 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69  the six least si
1f8a0 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67  gnificant.** dig
1f8b0 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20  its in the time 
1f8c0 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e  are meaningless.
1f8d0 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
1f8e0 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d  s of SQLite.** m
1f8f0 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65  ight provide gre
1f900 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20  ater resolution 
1f910 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20  on the profiler 
1f920 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a  callback.  The.*
1f930 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  * sqlite3_profil
1f940 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
1f950 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72  considered exper
1f960 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a  imental and is.*
1f970 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  * subject to cha
1f980 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65  nge in future ve
1f990 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1f9a0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
1f9b0 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33  e3_trace(sqlite3
1f9c0 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29  *, void(*xTrace)
1f9d0 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
1f9e0 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c  r*), void*);.SQL
1f9f0 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
1fa00 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70   void *sqlite3_p
1fa10 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c  rofile(sqlite3*,
1fa20 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69  .   void(*xProfi
1fa30 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  le)(void*,const 
1fa40 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69  char*,sqlite3_ui
1fa50 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  nt64), void*);..
1fa60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1fa70 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43  Query Progress C
1fa80 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
1fa90 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  The sqlite3_prog
1faa0 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e  ress_handler(D,N
1fab0 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20  ,X,P) interface 
1fac0 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62  causes the callb
1fad0 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
1fae0 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  X to be invoked 
1faf0 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72  periodically dur
1fb00 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67  ing long running
1fb10 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
1fb20 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b  lite3_exec()], [
1fb30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1fb40 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  and [sqlite3_get
1fb50 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a  _table()] for.**
1fb60 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1fb70 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d  tion D.  An exam
1fb80 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73  ple use for this
1fb90 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
1fba0 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75   to keep a GUI u
1fbb0 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20  pdated during a 
1fbc0 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a  large query..**.
1fbd0 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  ** ^The paramete
1fbe0 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68  r P is passed th
1fbf0 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c  rough as the onl
1fc00 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  y parameter to t
1fc10 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  he .** callback 
1fc20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68  function X.  ^Th
1fc30 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73  e parameter N is
1fc40 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65   the approximate
1fc50 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b   number of .** [
1fc60 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
1fc70 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68  instructions] th
1fc80 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  at are evaluated
1fc90 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73   between success
1fca0 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ive.** invocatio
1fcb0 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61  ns of the callba
1fcc0 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20  ck X.  ^If N is 
1fcd0 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68  less than one th
1fce0 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a  en the progress.
1fcf0 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69  ** handler is di
1fd00 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  sabled..**.** ^O
1fd10 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f  nly a single pro
1fd20 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61  gress handler ma
1fd30 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20  y be defined at 
1fd40 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20  one time per.** 
1fd50 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1fd60 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61  tion]; setting a
1fd70 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61   new progress ha
1fd80 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68  ndler cancels th
1fd90 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e  e.** old one.  ^
1fda0 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65  Setting paramete
1fdb0 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61  r X to NULL disa
1fdc0 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73  bles the progres
1fdd0 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54  s handler..** ^T
1fde0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
1fdf0 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61  ler is also disa
1fe00 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20  bled by setting 
1fe10 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73  N to a value les
1fe20 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a  s.** than 1..**.
1fe30 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72  ** ^If the progr
1fe40 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ess callback ret
1fe50 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
1fe60 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a  he operation is.
1fe70 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20  ** interrupted. 
1fe80 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61   This feature ca
1fe90 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70  n be used to imp
1fea0 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e  lement a.** "Can
1feb0 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61  cel" button on a
1fec0 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69   GUI progress di
1fed0 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20  alog box..**.** 
1fee0 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
1fef0 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  dler callback mu
1ff00 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
1ff10 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
1ff20 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
1ff30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
1ff40 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
1ff50 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1ff60 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
1ff70 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1ff80 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
1ff90 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
1ffa0 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
1ffb0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1ffc0 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
1ffd0 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
1ffe0 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
1fff0 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73  ph..**.*/.void s
20000 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
20010 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
20020 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f  , int, int(*)(vo
20030 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  id*), void*);../
20040 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
20050 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74  pening A New Dat
20060 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
20070 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
20080 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53  utines open an S
20090 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
200a0 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64  ile as specified
200b0 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65   by the .** file
200c0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e  name argument. ^
200d0 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  The filename arg
200e0 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72  ument is interpr
200f0 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f  eted as UTF-8 fo
20100 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
20110 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
20120 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73  open_v2() and as
20130 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
20140 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72  ative byte.** or
20150 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
20160 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64  open16(). ^(A [d
20170 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20180 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73  on] handle is us
20190 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65  ually.** returne
201a0 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e  d in *ppDb, even
201b0 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63   if an error occ
201c0 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65  urs.  The only e
201d0 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74  xception is that
201e0 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73  .** if SQLite is
201f0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
20200 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  ate memory to ho
20210 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  ld the [sqlite3]
20220 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55   object,.** a NU
20230 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74  LL will be writt
20240 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e  en into *ppDb in
20250 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74  stead of a point
20260 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
20270 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e  e3].** object.)^
20280 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61   ^(If the databa
20290 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e  se is opened (an
202a0 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75  d/or created) su
202b0 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e  ccessfully, then
202c0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  .** [SQLITE_OK] 
202d0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
202e0 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
202f0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
20300 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b  ned.)^ ^The.** [
20310 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
20320 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  ] or [sqlite3_er
20330 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e  rmsg16()] routin
20340 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  es can be used t
20350 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45  o obtain.** an E
20360 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20  nglish language 
20370 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74  description of t
20380 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69  he error followi
20390 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20  ng a failure of 
203a0 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  any.** of the sq
203b0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75  lite3_open() rou
203c0 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tines..**.** ^Th
203d0 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
203e0 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  ng for the datab
203f0 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ase will be UTF-
20400 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  8 if.** sqlite3_
20410 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
20420 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63  3_open_v2() is c
20430 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46  alled and.** UTF
20440 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
20450 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20  e byte order if 
20460 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
20470 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
20480 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61  Whether or not a
20490 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77  n error occurs w
204a0 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64  hen it is opened
204b0 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61  , resources.** a
204c0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
204d0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
204e0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
204f0 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73  should be releas
20500 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67  ed by.** passing
20510 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
20520 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74  close()] when it
20530 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65   is no longer re
20540 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  quired..**.** Th
20550 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  e sqlite3_open_v
20560 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f  2() interface wo
20570 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
20580 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70  _open().** excep
20590 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74  t that it accept
205a0 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  s two additional
205b0 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20   parameters for 
205c0 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72  additional contr
205d0 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e  ol.** over the n
205e0 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
205f0 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66  ection.  ^(The f
20600 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
20610 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
20620 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20  n_v2() can take 
20630 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f  one of.** the fo
20640 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61  llowing three va
20650 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79  lues, optionally
20660 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74   combined with t
20670 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  he .** [SQLITE_O
20680 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53  PEN_NOMUTEX], [S
20690 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
206a0 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
206b0 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
206c0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ,.** [SQLITE_OPE
206d0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c  N_PRIVATECACHE],
206e0 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f   and/or [SQLITE_
206f0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a  OPEN_URI] flags:
20700 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  )^.**.** <dl>.**
20710 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
20720 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64  PEN_READONLY]</d
20730 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
20740 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
20750 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f   in read-only mo
20760 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61  de.  If the data
20770 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  base does not.**
20780 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
20790 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
207a0 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
207b0 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
207c0 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
207d0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
207e0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
207f0 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
20800 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70  and writing if p
20810 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64  ossible, or read
20820 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74  ing.** only if t
20830 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65  he file is write
20840 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68   protected by th
20850 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
20860 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a  em.  In either.*
20870 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62  * case the datab
20880 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79  ase must already
20890 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73   exist, otherwis
208a0 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  e an error is re
208b0 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
208c0 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
208d0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
208e0 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
208f0 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a  N_CREATE]</dt>.*
20900 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
20910 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
20920 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
20930 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65  ting, and is cre
20940 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f  ated if.** it do
20950 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65  es not already e
20960 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68  xist. This is th
20970 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20  e behavior that 
20980 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66  is always used f
20990 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
209a0 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
209b0 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29  _open16().</dd>)
209c0 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a  ^.** </dl>.**.**
209d0 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
209e0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
209f0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f  _open_v2() is no
20a00 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  t one of the.** 
20a10 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f  combinations sho
20a20 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61  wn above optiona
20a30 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
20a40 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49  h other.** [SQLI
20a50 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
20a60 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a   | SQLITE_OPEN_*
20a70 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74   bits].** then t
20a80 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
20a90 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
20aa0 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
20ab0 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c  OPEN_NOMUTEX] fl
20ac0 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20  ag is set, then 
20ad0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
20ae0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73  nection.** opens
20af0 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68   in the multi-th
20b00 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
20b10 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73  mode] as long as
20b20 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65   the single-thre
20b30 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e  ad.** mode has n
20b40 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63  ot been set at c
20b50 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
20b60 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20  tart-time.  ^If 
20b70 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  the.** [SQLITE_O
20b80 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66  PEN_FULLMUTEX] f
20b90 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20  lag is set then 
20ba0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
20bb0 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a  nection opens.**
20bc0 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a   in the serializ
20bd0 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
20be0 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c  de] unless singl
20bf0 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20  e-thread was.** 
20c00 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63  previously selec
20c10 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  ted at compile-t
20c20 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
20c30 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  e..** ^The [SQLI
20c40 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
20c50 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
20c60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
20c70 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  nnection to be.*
20c80 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73  * eligible to us
20c90 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  e [shared cache 
20ca0 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73  mode], regardles
20cb0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
20cc0 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  not shared.** ca
20cd0 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75  che is enabled u
20ce0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e  sing [sqlite3_en
20cf0 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
20d00 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b  e()].  ^The.** [
20d10 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
20d20 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63  ATECACHE] flag c
20d30 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
20d40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
20d50 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70   not.** particip
20d60 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63  ate in [shared c
20d70 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20  ache mode] even 
20d80 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64  if it is enabled
20d90 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
20da0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
20db0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
20dc0 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  () is the name o
20dd0 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
20de0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68  3_vfs] object th
20df0 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f  at defines the o
20e00 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
20e10 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a  interface that.*
20e20 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  * the new databa
20e30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68  se connection sh
20e40 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74  ould use.  ^If t
20e50 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
20e60 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c  ter is.** a NULL
20e70 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
20e80 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
20e90 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69  e3_vfs] object i
20ea0 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s used..**.** ^I
20eb0 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
20ec0 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68  s ":memory:", th
20ed0 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
20ee0 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72  mporary in-memor
20ef0 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73  y database.** is
20f00 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65   created for the
20f10 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54   connection.  ^T
20f20 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  his in-memory da
20f30 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69  tabase will vani
20f40 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64  sh when.** the d
20f50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20f60 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46  on is closed.  F
20f70 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
20f80 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a  f SQLite might.*
20f90 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64  * make use of ad
20fa0 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c  ditional special
20fb0 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20   filenames that 
20fc0 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22  begin with the "
20fd0 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  :" character..**
20fe0 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   It is recommend
20ff0 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64  ed that when a d
21000 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
21010 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62   actually does b
21020 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22  egin with.** a "
21030 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75  :" character you
21040 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74   should prefix t
21050 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68  he filename with
21060 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68   a pathname such
21070 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61   as.** "./" to a
21080 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a  void ambiguity..
21090 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
210a0 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70  lename is an emp
210b0 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  ty string, then 
210c0 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
210d0 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20  rary.** on-disk 
210e0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
210f0 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73   created.  ^This
21100 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73   private databas
21110 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74  e will be.** aut
21120 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
21130 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68  ed as soon as th
21140 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
21150 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
21160 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c  .**.** [[URI fil
21170 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65  enames in sqlite
21180 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55  3_open()]] <h3>U
21190 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33  RI Filenames</h3
211a0 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49  >.**.** ^If [URI
211b0 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72   filename] inter
211c0 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61  pretation is ena
211d0 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69  bled, and the fi
211e0 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a  lename argument.
211f0 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22  ** begins with "
21200 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65  file:", then the
21210 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74   filename is int
21220 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52  erpreted as a UR
21230 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e  I. ^URI.** filen
21240 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
21250 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66  on is enabled if
21260 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
21270 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a  N_URI] flag is.*
21280 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75  * set in the fou
21290 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
212a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
212b0 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a  ), or if it has.
212c0 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20  ** been enabled 
212d0 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74  globally using t
212e0 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
212f0 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69  G_URI] option wi
21300 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  th the.** [sqlit
21310 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74  e3_config()] met
21320 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53  hod or by the [S
21330 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63  QLITE_USE_URI] c
21340 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
21350 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c  on..** As of SQL
21360 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
21370 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  7, URI filename 
21380 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
21390 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20  s turned off.** 
213a0 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20  by default, but 
213b0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
213c0 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
213d0 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e  enable URI filen
213e0 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ame.** interpret
213f0 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74  ation by default
21400 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c  .  See "[URI fil
21410 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64  enames]" for add
21420 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
21430 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52  mation..**.** UR
21440 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20  I filenames are 
21450 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67  parsed according
21460 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49   to RFC 3986. ^I
21470 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69  f the URI contai
21480 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69  ns an.** authori
21490 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74  ty, then it must
214a0 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d   be either an em
214b0 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68  pty string or th
214c0 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f  e string .** "lo
214d0 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68  calhost". ^If th
214e0 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e  e authority is n
214f0 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  ot an empty stri
21500 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74  ng or "localhost
21510 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20  ", an .** error 
21520 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74  is returned to t
21530 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20  he caller. ^The 
21540 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65  fragment compone
21550 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20  nt of a URI, if 
21560 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20  .** present, is 
21570 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
21580 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
21590 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  path component o
215a0 66 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65  f the URI as the
215b0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73   name of the dis
215c0 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20  k file.** which 
215d0 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74  contains the dat
215e0 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70  abase. ^If the p
215f0 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20  ath begins with 
21600 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c  a '/' character,
21610 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20   .** then it is 
21620 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
21630 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e  n absolute path.
21640 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f   ^If the path do
21650 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a  es not begin .**
21660 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61   with a '/' (mea
21670 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75  ning that the au
21680 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20  thority section 
21690 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
216a0 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e  the URI).** then
216b0 20 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74   the path is int
216c0 65 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65  erpreted as a re
216d0 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a  lative path. .**
216e0 20 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68   ^On windows, th
216f0 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e  e first componen
21700 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65  t of an absolute
21710 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64   path .** is a d
21720 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69  rive specificati
21730 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 0a  on (e.g. "C:")..
21740 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49  **.** [[core URI
21750 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
21760 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79  s]].** The query
21770 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
21780 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  URI may contain 
21790 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20  parameters that 
217a0 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a  are interpreted.
217b0 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c  ** either by SQL
217c0 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62  ite itself, or b
217d0 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f  y a [VFS | custo
217e0 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  m VFS implementa
217f0 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65  tion]..** SQLite
21800 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
21810 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20  following three 
21820 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
21830 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
21840 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62    <li> <b>vfs</b
21850 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61  >: ^The "vfs" pa
21860 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75  rameter may be u
21870 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74  sed to specify t
21880 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20  he name of.**   
21890 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74    a VFS object t
218a0 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65  hat provides the
218b0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
218c0 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
218d0 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62   should.**     b
218e0 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73  e used to access
218f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
21900 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20  le on disk. ^If 
21910 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73  this option is s
21920 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20  et to.**     an 
21930 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65  empty string the
21940 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a   default VFS obj
21950 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70  ect is used. ^Sp
21960 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e  ecifying an unkn
21970 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69  own.**     VFS i
21980 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20  s an error. ^If 
21990 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
219a0 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68  ) is used and th
219b0 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a  e vfs option is.
219c0 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20  **     present, 
219d0 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65  then the VFS spe
219e0 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70  cified by the op
219f0 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65  tion takes prece
21a00 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20  dence over.**   
21a10 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73    the value pass
21a20 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68  ed as the fourth
21a30 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
21a40 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
21a50 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  .**.**   <li> <b
21a60 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65  >mode</b>: ^(The
21a70 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20   mode parameter 
21a80 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69  may be set to ei
21a90 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c  ther "ro", "rw",
21aa0 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f  .**     "rwc", o
21ab0 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65  r "memory". Atte
21ac0 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74  mpting to set it
21ad0 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61   to any other va
21ae0 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e  lue is.**     an
21af0 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20   error)^. .**   
21b00 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70    ^If "ro" is sp
21b10 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68  ecified, then th
21b20 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
21b30 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e  ened for read-on
21b40 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  ly .**     acces
21b50 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68  s, just as if th
21b60 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
21b70 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61  EADONLY] flag ha
21b80 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68  d been set in th
21b90 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20  e .**     third 
21ba0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
21bb0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e  te3_open_v2(). ^
21bc0 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69  If the mode opti
21bd0 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a  on is set to .**
21be0 20 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20       "rw", then 
21bf0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
21c00 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d  opened for read-
21c10 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63  write (but not c
21c20 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61  reate) .**     a
21c30 63 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c  ccess, as if SQL
21c40 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
21c50 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49  TE (but not SQLI
21c60 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20  TE_OPEN_CREATE) 
21c70 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e  had .**     been
21c80 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77   set. ^Value "rw
21c90 63 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  c" is equivalent
21ca0 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68   to setting both
21cb0 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f   .**     SQLITE_
21cc0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61  OPEN_READWRITE a
21cd0 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  nd SQLITE_OPEN_C
21ce0 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20  REATE.  ^If the 
21cf0 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  mode option is.*
21d00 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65  *     set to "me
21d10 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72  mory" then a pur
21d20 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  e [in-memory dat
21d30 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65  abase] that neve
21d40 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f  r reads.**     o
21d50 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69  r writes from di
21d60 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20  sk is used. ^It 
21d70 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73  is an error to s
21d80 70 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66  pecify a value f
21d90 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f  or.**     the mo
21da0 64 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  de parameter tha
21db0 74 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69  t is less restri
21dc0 63 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20  ctive than that 
21dd0 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
21de0 20 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61      the flags pa
21df0 73 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72  ssed in the thir
21e00 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
21e10 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
21e20 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  ..**.**   <li> <
21e30 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68  b>cache</b>: ^Th
21e40 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65  e cache paramete
21e50 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20  r may be set to 
21e60 65 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20  either "shared" 
21e70 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61  or.**     "priva
21e80 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74  te". ^Setting it
21e90 20 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20   to "shared" is 
21ea0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
21eb0 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20  tting the.**    
21ec0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
21ed0 52 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20  REDCACHE bit in 
21ee0 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
21ef0 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  nt passed to.** 
21f00 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e      sqlite3_open
21f10 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20  _v2(). ^Setting 
21f20 74 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65  the cache parame
21f30 74 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22  ter to "private"
21f40 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69   is .**     equi
21f50 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
21f60 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  g the SQLITE_OPE
21f70 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62  N_PRIVATECACHE b
21f80 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73  it..**     ^If s
21f90 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
21fa0 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65   is used and the
21fb0 20 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74   "cache" paramet
21fc0 65 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e  er is present in
21fd0 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69  .**     a URI fi
21fe0 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75  lename, its valu
21ff0 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20  e overrides any 
22000 62 65 68 61 76 69 6f 72 20 72 65 71 75 65 73 74  behavior request
22010 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a  ed by setting.**
22020 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
22030 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72  _PRIVATECACHE or
22040 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
22050 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a  REDCACHE flag..*
22060 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73  *.**  <li> <b>ps
22070 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f  ow</b>: ^The pso
22080 77 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  w parameter may 
22090 62 65 20 22 74 72 75 65 22 20 28 6f 72 20 22 6f  be "true" (or "o
220a0 6e 22 20 6f 72 20 22 79 65 73 22 20 6f 72 0a 2a  n" or "yes" or.*
220b0 2a 20 20 20 20 20 22 31 22 29 20 6f 72 20 22 66  *     "1") or "f
220c0 61 6c 73 65 22 20 28 6f 72 20 22 6f 66 66 22 20  alse" (or "off" 
220d0 6f 72 20 22 6e 6f 22 20 6f 72 20 22 30 22 29 20  or "no" or "0") 
220e0 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
220f0 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77   the.**     [pow
22100 65 72 73 61 66 65 20 6f 76 65 72 77 72 69 74 65  ersafe overwrite
22110 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20  ] property does 
22120 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c  or does not appl
22130 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  y to the.**     
22140 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e  storage media on
22150 20 77 68 69 63 68 20 74 68 65 20 64 61 74 61 62   which the datab
22160 61 73 65 20 66 69 6c 65 20 72 65 73 69 64 65 73  ase file resides
22170 2e 20 20 5e 54 68 65 20 70 73 6f 77 20 71 75 65  .  ^The psow que
22180 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65  ry.**     parame
22190 74 65 72 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 66  ter only works f
221a0 6f 72 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20  or the built-in 
221b0 75 6e 69 78 20 61 6e 64 20 57 69 6e 64 6f 77 73  unix and Windows
221c0 20 56 46 53 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c   VFSes..**.**  <
221d0 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62  li> <b>nolock</b
221e0 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70  >: ^The nolock p
221f0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f  arameter is a bo
22200 6f 6c 65 61 6e 20 71 75 65 72 79 20 70 61 72 61  olean query para
22210 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 77 68 69  meter.**     whi
22220 63 68 20 69 66 20 73 65 74 20 64 69 73 61 62 6c  ch if set disabl
22230 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20  es file locking 
22240 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72  in rollback jour
22250 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69 73  nal modes.  This
22260 0a 2a 2a 20 20 20 20 20 69 73 20 75 73 65 66 75  .**     is usefu
22270 6c 20 66 6f 72 20 61 63 63 65 73 73 69 6e 67 20  l for accessing 
22280 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20 61 20  a database on a 
22290 66 69 6c 65 73 79 73 74 65 6d 20 74 68 61 74 20  filesystem that 
222a0 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20  does not.**     
222b0 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e  support locking.
222c0 20 20 43 61 75 74 69 6f 6e 3a 20 20 44 61 74 61    Caution:  Data
222d0 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 20  base corruption 
222e0 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
222f0 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f  two.**     or mo
22300 72 65 20 70 72 6f 63 65 73 73 65 73 20 77 72 69  re processes wri
22310 74 65 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64  te to the same d
22320 61 74 61 62 61 73 65 20 61 6e 64 20 61 6e 79 20  atabase and any 
22330 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20  one of those.** 
22340 20 20 20 20 70 72 6f 63 65 73 73 65 73 20 75 73      processes us
22350 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a  es nolock=1..**.
22360 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75  **  <li> <b>immu
22370 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20  table</b>: ^The 
22380 69 6d 6d 75 74 61 62 6c 65 20 70 61 72 61 6d 65  immutable parame
22390 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e  ter is a boolean
223a0 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70 61   query.**     pa
223b0 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 6e 64  rameter that ind
223c0 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20  icates that the 
223d0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73  database file is
223e0 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20   stored on.**   
223f0 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69    read-only medi
22400 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61  a.  ^When immuta
22410 62 6c 65 20 69 73 20 73 65 74 2c 20 53 51 4c 69  ble is set, SQLi
22420 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
22430 74 68 65 0a 2a 2a 20 20 20 20 20 64 61 74 61 62  the.**     datab
22440 61 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20  ase file cannot 
22450 62 65 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e  be changed, even
22460 20 62 79 20 61 20 70 72 6f 63 65 73 73 20 77 69   by a process wi
22470 74 68 20 68 69 67 68 65 72 0a 2a 2a 20 20 20 20  th higher.**    
22480 20 70 72 69 76 69 6c 65 67 65 2c 20 61 6e 64 20   privilege, and 
22490 73 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  so the database 
224a0 69 73 20 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f  is opened read-o
224b0 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b  nly and all lock
224c0 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63  ing.**     and c
224d0 68 61 6e 67 65 20 64 65 74 65 63 74 69 6f 6e 20  hange detection 
224e0 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 43 61  is disabled.  Ca
224f0 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74  ution: Setting t
22500 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20  he immutable.** 
22510 20 20 20 20 70 72 6f 70 65 72 74 79 20 6f 6e 20      property on 
22520 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
22530 74 68 61 74 20 64 6f 65 73 20 69 6e 20 66 61 63  that does in fac
22540 74 20 63 68 61 6e 67 65 20 63 61 6e 20 72 65 73  t change can res
22550 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e  ult.**     in in
22560 63 6f 72 72 65 63 74 20 71 75 65 72 79 20 72 65  correct query re
22570 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51  sults and/or [SQ
22580 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 20 65 72  LITE_CORRUPT] er
22590 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65  rors..**     See
225a0 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49   also: [SQLITE_I
225b0 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e  OCAP_IMMUTABLE].
225c0 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f  .**       .** </
225d0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69  ul>.**.** ^Speci
225e0 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e  fying an unknown
225f0 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
22600 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
22610 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f  t of a URI is no
22620 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20  t an.** error.  
22630 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
22640 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
22650 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74  understand addit
22660 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70  ional query.** p
22670 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20  arameters.  See 
22680 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  "[query paramete
22690 72 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20  rs with special 
226a0 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74  meaning to SQLit
226b0 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74  e]" for.** addit
226c0 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
226d0 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  n..**.** [[URI f
226e0 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
226f0 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e  ]] <h3>URI filen
22700 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33  ame examples</h3
22710 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  >.**.** <table b
22720 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d  order="1" align=
22730 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69  center cellpaddi
22740 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ng=5>.** <tr><th
22750 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  > URI filenames 
22760 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20  <th> Results.** 
22770 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
22780 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20  ta.db <td> .**  
22790 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
227a0 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
227b0 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  in the current d
227c0 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72  irectory..** <tr
227d0 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65  ><td> file:/home
227e0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72  /fred/data.db<br
227f0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69  >.**          fi
22800 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f  le:///home/fred/
22810 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a  data.db <br> .**
22820 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
22830 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f  /localhost/home/
22840 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
22850 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  > <td> .**      
22860 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74      Open the dat
22870 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d  abase file "/hom
22880 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e  e/fred/data.db".
22890 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
228a0 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d  e://darkstar/hom
228b0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
228c0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
228d0 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b   An error. "dark
228e0 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72  star" is not a r
228f0 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72  ecognized author
22900 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20  ity..** <tr><td 
22910 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61  style="white-spa
22920 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20  ce:nowrap"> .** 
22930 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
22940 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30  /C:/Documents%20
22950 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66  and%20Settings/f
22960 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61  red/Desktop/data
22970 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20  .db.**     <td> 
22980 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70  Windows only: Op
22990 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74  en the file "dat
229a0 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20  a.db" on fred's 
229b0 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65  desktop on drive
229c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e  .**          C:.
229d0 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25   Note that the %
229e0 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74  20 escaping in t
229f0 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e  his example is n
22a00 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20  ot strictly .** 
22a10 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61           necessa
22a20 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61  ry - space chara
22a30 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65  cters can be use
22a40 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20  d literally.**  
22a50 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66          in URI f
22a60 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72  ilenames..** <tr
22a70 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
22a80 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65  db?mode=ro&cache
22a90 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a  =private <td> .*
22aa0 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
22ab0 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69  file "data.db" i
22ac0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69  n the current di
22ad0 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64  rectory for read
22ae0 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a  -only access..**
22af0 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64            Regard
22b00 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
22b10 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61  or not shared-ca
22b20 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62  che mode is enab
22b30 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  led by.**       
22b40 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20     default, use 
22b50 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e  a private cache.
22b60 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
22b70 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  e:/home/fred/dat
22b80 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f  a.db?vfs=unix-do
22b90 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20  tfile <td>.**   
22ba0 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
22bb0 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74   "/home/fred/dat
22bc0 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73  a.db". Use the s
22bd0 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78  pecial VFS "unix
22be0 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20  -dotfile".**    
22bf0 20 20 20 20 20 20 74 68 61 74 20 75 73 65 73 20        that uses 
22c00 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61  dot-files in pla
22c10 63 65 20 6f 66 20 70 6f 73 69 78 20 61 64 76 69  ce of posix advi
22c20 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a  sory locking..**
22c30 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
22c40 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64  ata.db?mode=read
22c50 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  only <td> .**   
22c60 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e         An error.
22c70 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e   "readonly" is n
22c80 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f  ot a valid optio
22c90 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22  n for the "mode"
22ca0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c   parameter..** <
22cb0 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55  /table>.**.** ^U
22cc0 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65  RI hexadecimal e
22cd0 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20  scape sequences 
22ce0 28 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72  (%HH) are suppor
22cf0 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70  ted within the p
22d00 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79  ath and.** query
22d10 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
22d20 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69   URI. A hexadeci
22d30 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
22d40 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20  nce consists of 
22d50 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67  a.** percent sig
22d60 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77  n - "%" - follow
22d70 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77  ed by exactly tw
22d80 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69  o hexadecimal di
22d90 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79  gits .** specify
22da0 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c  ing an octet val
22db0 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20  ue. ^Before the 
22dc0 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f  path or query co
22dd0 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a  mponents of a.**
22de0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72   URI filename ar
22df0 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74  e interpreted, t
22e00 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20  hey are encoded 
22e10 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20  using UTF-8 and 
22e20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69  all .** hexadeci
22e30 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
22e40 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79  nces replaced by
22e50 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63   a single byte c
22e60 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a  ontaining the.**
22e70 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f   corresponding o
22e80 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72  ctet. If this pr
22e90 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20  ocess generates 
22ea0 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38  an invalid UTF-8
22eb0 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68   encoding,.** th
22ec0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
22ed0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  defined..**.** <
22ee0 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
22ef0 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  s users:</b>  Th
22f00 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  e encoding used 
22f10 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  for the filename
22f20 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20   argument.** of 
22f30 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
22f40 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
22f50 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46  v2() must be UTF
22f60 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72  -8, not whatever
22f70 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20  .** codepage is 
22f80 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
22f90 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f  d.  Filenames co
22fa0 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61  ntaining interna
22fb0 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63  tional.** charac
22fc0 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e  ters must be con
22fd0 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20  verted to UTF-8 
22fe0 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67  prior to passing
22ff0 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71   them into.** sq
23000 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
23010 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
23020 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  )..**.** <b>Note
23030 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74   to Windows Runt
23040 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20  ime users:</b>  
23050 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69  The temporary di
23060 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20  rectory must be 
23070 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  set.** prior to 
23080 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  calling sqlite3_
23090 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
230a0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74  3_open_v2().  Ot
230b0 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73  herwise, various
230c0 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 61  .** features tha
230d0 74 20 72 65 71 75 69 72 65 20 74 68 65 20 75 73  t require the us
230e0 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66  e of temporary f
230f0 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a  iles may fail..*
23100 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
23110 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72  sqlite3_temp_dir
23120 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73  ectory].*/.int s
23130 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63  qlite3_open(.  c
23140 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e  onst char *filen
23150 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
23160 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
23170 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  -8) */.  sqlite3
23180 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
23190 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
231a0 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
231b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
231c0 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  16(.  const void
231d0 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
231e0 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
231f0 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20  me (UTF-16) */. 
23200 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
23210 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
23220 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
23230 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  e */.);.int sqli
23240 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63  te3_open_v2(.  c
23250 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e  onst char *filen
23260 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
23270 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
23280 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  -8) */.  sqlite3
23290 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20   **ppDb,        
232a0 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
232b0 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69  db handle */.  i
232c0 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20  nt flags,       
232d0 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20         /* Flags 
232e0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
232f0 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20  *zVfs        /* 
23300 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75  Name of VFS modu
23310 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a  le to use */.);.
23320 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23330 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46   Obtain Values F
23340 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 72  or URI Parameter
23350 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72  s.**.** These ar
23360 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e  e utility routin
23370 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46  es, useful to VF
23380 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
23390 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a  s, that check.**
233a0 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 74   to see if a dat
233b0 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 61  abase file was a
233c0 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69   URI that contai
233d0 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 20 71  ned a specific q
233e0 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74  uery .** paramet
233f0 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62  er, and if so ob
23400 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20  tains the value 
23410 6f 66 20 74 68 61 74 20 71 75 65 72 79 20 70 61  of that query pa
23420 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
23430 66 20 46 20 69 73 20 74 68 65 20 64 61 74 61 62  f F is the datab
23440 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69  ase filename poi
23450 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f  nter passed into
23460 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74   the xOpen() met
23470 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53  hod of .** a VFS
23480 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
23490 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70  when the flags p
234a0 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
234b0 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a  n() has one or .
234c0 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b  ** more of the [
234d0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
234e0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e   or [SQLITE_OPEN
234f0 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73  _MAIN_DB] bits s
23500 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74  et and.** P is t
23510 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71  he name of the q
23520 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20  uery parameter, 
23530 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
23540 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c  uri_parameter(F,
23550 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 76  P) returns the v
23560 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a  alue of the P.**
23570 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 74   parameter if it
23580 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c   exists or a NUL
23590 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64  L pointer if P d
235a0 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61  oes not appear a
235b0 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61  s a .** query pa
235c0 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49  rameter on F.  I
235d0 66 20 50 20 69 73 20 61 20 71 75 65 72 79 20 70  f P is a query p
235e0 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a  arameter of F.**
235f0 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74   has no explicit
23600 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c   value, then sql
23610 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
23620 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a  er(F,P) returns.
23630 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
23640 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e  an empty string.
23650 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
23660 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
23670 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73  ,P,B) routine as
23680 73 75 6d 65 73 20 74 68 61 74 20 50 20 69 73 20  sumes that P is 
23690 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72  a boolean.** par
236a0 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72  ameter and retur
236b0 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72 20 66  ns true (1) or f
236c0 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64 69  alse (0) accordi
236d0 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a  ng to the value.
236e0 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71  ** of P.  The sq
236f0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
23700 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
23710 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31   returns true (1
23720 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75  ) if the.** valu
23730 65 20 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d  e of query param
23740 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66  eter P is one of
23750 20 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20   "yes", "true", 
23760 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a  or "on" in any.*
23770 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74 68 65  * case or if the
23780 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69   value begins wi
23790 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75  th a non-zero nu
237a0 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73  mber.  The .** s
237b0 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
237c0 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
237d0 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65  es returns false
237e0 20 28 30 29 20 69 66 20 74 68 65 20 76 61 6c 75   (0) if the valu
237f0 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61  e of.** query pa
23800 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65  rameter P is one
23810 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65   of "no", "false
23820 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61  ", or "off" in a
23830 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66  ny case or.** if
23840 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e   the value begin
23850 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63  s with a numeric
23860 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20   zero.  If P is 
23870 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70  not a query.** p
23880 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72  arameter on F or
23890 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   if the value of
238a0 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d   P is does not m
238b0 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a  atch any of the.
238c0 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73  ** above, then s
238d0 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
238e0 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e  an(F,P,B) return
238f0 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20  s (B!=0)..**.** 
23900 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
23910 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75  int64(F,P,D) rou
23920 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68  tine converts th
23930 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74  e value of P int
23940 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69  o a.** 64-bit si
23950 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64  gned integer and
23960 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e   returns that in
23970 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50  teger, or D if P
23980 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69   does not.** exi
23990 73 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75  st.  If the valu
239a0 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68  e of P is someth
239b0 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61  ing other than a
239c0 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a  n integer, then.
239d0 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72  ** zero is retur
239e0 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46  ned..** .** If F
239f0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
23a00 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  er, then sqlite3
23a10 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
23a20 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  ,P) returns NULL
23a30 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
23a40 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
23a50 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49  B) returns B.  I
23a60 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c  f F is not a NUL
23a70 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a  L pointer and.**
23a80 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61   is not a databa
23a90 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  se file pathname
23aa0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51   pointer that SQ
23ab0 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f  Lite passed into
23ac0 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46   the xOpen.** VF
23ad0 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74  S method, then t
23ae0 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74  he behavior of t
23af0 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75  his routine is u
23b00 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
23b10 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72  bably.** undesir
23b20 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  able..*/.const c
23b30 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69  har *sqlite3_uri
23b40 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74  _parameter(const
23b50 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
23b60 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50  , const char *zP
23b70 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74  aram);.int sqlit
23b80 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63  e3_uri_boolean(c
23b90 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
23ba0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50  , const char *zP
23bb0 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75  aram, int bDefau
23bc0 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  lt);.sqlite3_int
23bd0 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69  64 sqlite3_uri_i
23be0 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a  nt64(const char*
23bf0 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73  , const char*, s
23c00 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a  qlite3_int64);..
23c10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23c20 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64   Error Codes And
23c30 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20   Messages.**.** 
23c40 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
23c50 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65  code() interface
23c60 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
23c70 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64  eric [result cod
23c80 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  e] or.** [extend
23c90 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
23ca0 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63  for the most rec
23cb0 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74  ent failed sqlit
23cc0 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a  e3_* API call.**
23cd0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
23ce0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
23cf0 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70  nection]. If a p
23d00 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61  rior API call fa
23d10 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20  iled.** but the 
23d20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20  most recent API 
23d30 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20  call succeeded, 
23d40 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
23d50 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33   from.** sqlite3
23d60 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e  _errcode() is un
23d70 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73  defined.  ^The s
23d80 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
23d90 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74  errcode().** int
23da0 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61  erface is the sa
23db0 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69  me except that i
23dc0 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  t always returns
23dd0 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64   the .** [extend
23de0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
23df0 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64  even when extend
23e00 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
23e10 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e  are.** disabled.
23e20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
23e30 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64  te3_errmsg() and
23e40 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31   sqlite3_errmsg1
23e50 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69  6() return Engli
23e60 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74  sh-language.** t
23e70 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62  ext that describ
23e80 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73  es the error, as
23e90 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
23ea0 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69   UTF-16 respecti
23eb0 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72  vely..** ^(Memor
23ec0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72  y to hold the er
23ed0 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
23ee0 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e  ng is managed in
23ef0 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65  ternally..** The
23f00 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
23f10 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f  s not need to wo
23f20 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e  rry about freein
23f30 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a  g the result..**
23f40 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72   However, the er
23f50 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74  ror string might
23f60 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
23f70 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62  or deallocated b
23f80 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  y.** subsequent 
23f90 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53  calls to other S
23fa0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20  QLite interface 
23fb0 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a  functions.)^.**.
23fc0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
23fd0 65 72 72 73 74 72 28 29 20 69 6e 74 65 72 66 61  errstr() interfa
23fe0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 45  ce returns the E
23ff0 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20  nglish-language 
24000 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73  text.** that des
24010 63 72 69 62 65 73 20 74 68 65 20 5b 72 65 73 75  cribes the [resu
24020 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46  lt code], as UTF
24030 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20  -8..** ^(Memory 
24040 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f  to hold the erro
24050 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
24060 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65   is managed inte
24070 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75  rnally.** and mu
24080 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20  st not be freed 
24090 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
240a0 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  on)^..**.** When
240b0 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
240c0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
240d0 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d   is in use, it m
240e0 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63  ight be the.** c
240f0 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e  ase that a secon
24100 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f  d error occurs o
24110 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  n a separate thr
24120 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a  ead in between.*
24130 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68  * the time of th
24140 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e  e first error an
24150 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68  d the call to th
24160 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  ese interfaces..
24170 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70  ** When that hap
24180 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64  pens, the second
24190 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72   error will be r
241a0 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68  eported since th
241b0 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ese.** interface
241c0 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20  s always report 
241d0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
241e0 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69  result.  To avoi
241f0 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20  d.** this, each 
24200 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69  thread can obtai
24210 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20  n exclusive use 
24220 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
24230 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a   connection] D.*
24240 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73  * by invoking [s
24250 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
24260 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  er]([sqlite3_db_
24270 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72  mutex](D)) befor
24280 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74  e beginning.** t
24290 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f  o use D and invo
242a0 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
242b0 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69  tex_leave]([sqli
242c0 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
242d0 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63  ) after.** all c
242e0 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65  alls to the inte
242f0 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65  rfaces listed he
24300 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64  re are completed
24310 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e  ..**.** If an in
24320 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69  terface fails wi
24330 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  th SQLITE_MISUSE
24340 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
24350 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61   interface.** wa
24360 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72  s invoked incorr
24370 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70  ectly by the app
24380 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68  lication.  In th
24390 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20  at case, the.** 
243a0 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d  error code and m
243b0 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61  essage may or ma
243c0 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f  y not be set..*/
243d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72  .int sqlite3_err
243e0 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
243f0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  );.int sqlite3_e
24400 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
24410 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f  sqlite3 *db);.co
24420 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
24430 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33  3_errmsg(sqlite3
24440 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
24450 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
24460 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73  (sqlite3*);.cons
24470 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
24480 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a  errstr(int);../*
24490 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
244a0 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  L Statement Obje
244b0 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
244c0 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
244d0 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73  ent} {prepared s
244e0 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a  tatements}.**.**
244f0 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
24500 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72  this object repr
24510 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20  esents a single 
24520 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  SQL statement..*
24530 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
24540 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e   variously known
24550 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20   as a "prepared 
24560 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a  statement" or a.
24570 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c  ** "compiled SQL
24580 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73   statement" or s
24590 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74  imply as a "stat
245a0 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68  ement"..**.** Th
245b0 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74  e life of a stat
245c0 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65  ement object goe
245d0 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65  s something like
245e0 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   this:.**.** <ol
245f0 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65  >.** <li> Create
24600 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
24610 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
24620 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65  re_v2()] or a re
24630 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75  lated.**      fu
24640 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20  nction..** <li> 
24650 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b  Bind values to [
24660 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d  host parameters]
24670 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
24680 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20  e3_bind_*().**  
24690 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a      interfaces..
246a0 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
246b0 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
246c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
246d0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
246e0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
246f0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75   the statement u
24700 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
24710 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62  set()] then go b
24720 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73  ack.**      to s
24730 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20  tep 2.  Do this 
24740 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d  zero or more tim
24750 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74  es..** <li> Dest
24760 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75  roy the object u
24770 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
24780 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f  nalize()]..** </
24790 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20  ol>.**.** Refer 
247a0 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  to documentation
247b0 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d   on individual m
247c0 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72  ethods above for
247d0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
247e0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74  nformation..*/.t
247f0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
24800 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74  lite3_stmt sqlit
24810 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_stmt;../*.** 
24820 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69  CAPI3REF: Run-ti
24830 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20  me Limits.**.** 
24840 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  ^(This interface
24850 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65   allows the size
24860 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73   of various cons
24870 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d  tructs to be lim
24880 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e  ited.** on a con
24890 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65  nection by conne
248a0 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68  ction basis.  Th
248b0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
248c0 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74  r is the.** [dat
248d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
248e0 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73  ] whose limit is
248f0 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75   to be set or qu
24900 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73  eried.  The.** s
24910 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
24920 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c  is one of the [l
24930 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d  imit categories]
24940 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a   that define a.*
24950 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74  * class of const
24960 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65  ructs to be size
24970 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74   limited.  The t
24980 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
24990 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d  s the.** new lim
249a0 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73  it for that cons
249b0 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  truct.)^.**.** ^
249c0 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74  If the new limit
249d0 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e   is a negative n
249e0 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74  umber, the limit
249f0 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
24a00 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d  * ^(For each lim
24a10 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49  it category SQLI
24a20 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45  TE_LIMIT_<i>NAME
24a30 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20  </i> there is a 
24a40 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61  .** [limits | ha
24a50 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a  rd upper bound].
24a60 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  ** set at compil
24a70 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72  e-time by a C pr
24a80 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
24a90 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69   called.** [limi
24aa0 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ts | SQLITE_MAX_
24ab0 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a  <i>NAME</i>]..**
24ac0 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20   (The "_LIMIT_" 
24ad0 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63  in the name is c
24ae0 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f  hanged to "_MAX_
24af0 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70  ".))^.** ^Attemp
24b00 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61  ts to increase a
24b10 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73   limit above its
24b20 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
24b30 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c  d are.** silentl
24b40 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74  y truncated to t
24b50 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  he hard upper bo
24b60 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61  und..**.** ^Rega
24b70 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
24b80 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d  r or not the lim
24b90 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20  it was changed, 
24ba0 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
24bb0 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66  _limit()] interf
24bc0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
24bd0 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
24be0 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65  he limit..** ^He
24bf0 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65  nce, to find the
24c00 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
24c10 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75  f a limit withou
24c20 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a  t changing it,.*
24c30 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20  * simply invoke 
24c40 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77  this interface w
24c50 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61  ith the third pa
24c60 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d  rameter set to -
24c70 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d  1..**.** Run-tim
24c80 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74  e limits are int
24c90 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
24ca0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   applications th
24cb0 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74  at manage.** bot
24cc0 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65  h their own inte
24cd0 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e  rnal database an
24ce0 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73  d also databases
24cf0 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f   that are contro
24d00 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75  lled.** by untru
24d10 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f  sted external so
24d20 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70  urces.  An examp
24d30 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  le application m
24d40 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62  ight be a.** web
24d50 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61   browser that ha
24d60 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61  s its own databa
24d70 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ses for storing 
24d80 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73  history and.** s
24d90 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65  eparate database
24da0 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20  s controlled by 
24db0 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69  JavaScript appli
24dc0 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64  cations download
24dd0 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e  ed.** off the In
24de0 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74  ternet.  The int
24df0 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20  ernal databases 
24e00 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65  can be given the
24e10 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75  .** large, defau
24e20 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61  lt limits.  Data
24e30 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79  bases managed by
24e40 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
24e50 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65  s can.** be give
24e60 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c  n much smaller l
24e70 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74  imits designed t
24e80 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69  o prevent a deni
24e90 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a  al of service.**
24ea0 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f   attack.  Develo
24eb0 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  pers might also 
24ec0 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20  want to use the 
24ed0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
24ee0 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e  horizer()].** in
24ef0 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68  terface to furth
24f00 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75  er control untru
24f10 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73  sted SQL.  The s
24f20 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ize of the datab
24f30 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  ase.** created b
24f40 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  y an untrusted s
24f50 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e  cript can be con
24f60 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  tained using the
24f70 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  .** [max_page_co
24f80 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a  unt] [PRAGMA]..*
24f90 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d  *.** New run-tim
24fa0 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  e limit categori
24fb0 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  es may be added 
24fc0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
24fd0 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  es..*/.int sqlit
24fe0 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33  e3_limit(sqlite3
24ff0 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e  *, int id, int n
25000 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ewVal);../*.** C
25010 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
25020 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69  e Limit Categori
25030 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
25040 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d  {limit category}
25050 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72   {*limit categor
25060 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ies}.**.** These
25070 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
25080 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72  e various perfor
25090 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20  mance limits.** 
250a0 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65  that can be lowe
250b0 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20  red at run-time 
250c0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
250d0 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  imit()]..** The 
250e0 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20  synopsis of the 
250f0 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20  meanings of the 
25100 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69  various limits i
25110 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a  s shown below..*
25120 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * Additional inf
25130 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69  ormation is avai
25140 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73  lable at [limits
25150 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c   | Limits in SQL
25160 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  ite]..**.** <dl>
25170 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
25180 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64  IT_LENGTH]] ^(<d
25190 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
251a0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
251b0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69  d>The maximum si
251c0 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67  ze of any string
251d0 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c   or BLOB or tabl
251e0 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e  e row, in bytes.
251f0 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  <dd>)^.**.** [[S
25200 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
25210 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
25220 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
25230 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
25240 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
25250 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20  ength of an SQL 
25260 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79  statement, in by
25270 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  tes.</dd>)^.**.*
25280 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
25290 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e  _COLUMN]] ^(<dt>
252a0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
252b0 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  UMN</dt>.** <dd>
252c0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
252d0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
252e0 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74   a table definit
252f0 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a  ion or in the.**
25300 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
25310 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65   [SELECT] or the
25320 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
25330 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e  of columns in an
25340 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20   index.** or in 
25350 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47  an ORDER BY or G
25360 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c  ROUP BY clause.<
25370 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
25380 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
25390 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
253a0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
253b0 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
253c0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
253d0 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73  epth of the pars
253e0 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78  e tree on any ex
253f0 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  pression.</dd>)^
25400 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
25410 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
25420 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51  ELECT]] ^(<dt>SQ
25430 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
25440 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a  UND_SELECT</dt>.
25450 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
25460 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72  um number of ter
25470 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64  ms in a compound
25480 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
25490 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  t.</dd>)^.**.** 
254a0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
254b0 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53  DBE_OP]] ^(<dt>S
254c0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
254d0 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  _OP</dt>.** <dd>
254e0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
254f0 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f  er of instructio
25500 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20  ns in a virtual 
25510 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a  machine program.
25520 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  ** used to imple
25530 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74  ment an SQL stat
25540 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d  ement.  This lim
25550 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  it is not curren
25560 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c  tly.** enforced,
25570 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67   though that mig
25580 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73  ht be added in s
25590 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
255a0 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e  se of.** SQLite.
255b0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
255c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
255d0 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64  CTION_ARG]] ^(<d
255e0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  t>SQLITE_LIMIT_F
255f0 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e  UNCTION_ARG</dt>
25600 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
25610 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  mum number of ar
25620 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e  guments on a fun
25630 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ction.</dd>)^.**
25640 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
25650 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28  IT_ATTACHED]] ^(
25660 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
25670 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a  _ATTACHED</dt>.*
25680 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
25690 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54  m number of [ATT
256a0 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64  ACH | attached d
256b0 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64  atabases].)^</dd
256c0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
256d0 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
256e0 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20  ERN_LENGTH]].** 
256f0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
25700 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
25710 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
25720 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
25730 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74  ength of the pat
25740 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f  tern argument to
25750 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a   the [LIKE] or.*
25760 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  * [GLOB] operato
25770 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
25780 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
25790 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
257a0 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
257b0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
257c0 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20  _NUMBER</dt>.** 
257d0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
257e0 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20  index number of 
257f0 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  any [parameter] 
25800 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
25810 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ent.)^.**.** [[S
25820 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
25830 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  GER_DEPTH]] ^(<d
25840 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  t>SQLITE_LIMIT_T
25850 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74  RIGGER_DEPTH</dt
25860 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
25870 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65  imum depth of re
25880 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67  cursion for trig
25890 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  gers.</dd>)^.** 
258a0 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
258b0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45   SQLITE_LIMIT_LE
258c0 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
258d0 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
258e0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  e SQLITE_LIMIT_S
258f0 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  QL_LENGTH       
25900 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
25910 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
25920 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20  COLUMN          
25930 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
25940 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
25950 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20  _EXPR_DEPTH     
25960 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65             3.#de
25970 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
25980 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
25990 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64  T           4.#d
259a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
259b0 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20  IT_VDBE_OP      
259c0 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
259d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
259e0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
259f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
25a00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
25a10 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20  IMIT_ATTACHED   
25a20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37                 7
25a30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
25a40 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
25a50 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  RN_LENGTH       
25a60 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
25a70 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
25a80 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20  NUMBER          
25a90 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
25aa0 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
25ab0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
25ac0 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   10../*.** CAPI3
25ad0 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41  REF: Compiling A
25ae0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
25af0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
25b00 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
25b10 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65  iler}.**.** To e
25b20 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75  xecute an SQL qu
25b30 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72  ery, it must fir
25b40 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69  st be compiled i
25b50 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a  nto a byte-code.
25b60 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67  ** program using
25b70 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f   one of these ro
25b80 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
25b90 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
25ba0 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61  , "db", is a [da
25bb0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25bc0 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  n] obtained from
25bd0 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63   a.** prior succ
25be0 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
25bf0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
25c00 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
25c10 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  2()] or.** [sqli
25c20 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20  te3_open16()].  
25c30 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  The database con
25c40 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  nection must not
25c50 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65   have been close
25c60 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  d..**.** The sec
25c70 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a  ond argument, "z
25c80 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61  Sql", is the sta
25c90 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
25ca0 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a  piled, encoded.*
25cb0 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  * as either UTF-
25cc0 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68  8 or UTF-16.  Th
25cd0 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
25ce0 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
25cf0 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20  prepare_v2().** 
25d00 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55  interfaces use U
25d10 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65  TF-8, and sqlite
25d20 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e  3_prepare16() an
25d30 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
25d40 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20  e16_v2().** use 
25d50 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49  UTF-16..**.** ^I
25d60 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75  f the nByte argu
25d70 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61  ment is less tha
25d80 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71  n zero, then zSq
25d90 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20  l is read up to 
25da0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72  the.** first zer
25db0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49  o terminator. ^I
25dc0 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e  f nByte is non-n
25dd0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74  egative, then it
25de0 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a   is the maximum.
25df0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79  ** number of  by
25e00 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53  tes read from zS
25e10 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65  ql.  ^When nByte
25e20 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
25e30 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74  , the.** zSql st
25e40 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74  ring ends at eit
25e50 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c  her the first '\
25e60 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27  000' or '\u0000'
25e70 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a   character or.**
25e80 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79   the nByte-th by
25e90 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  te, whichever co
25ea0 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68  mes first. If th
25eb0 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a  e caller knows.*
25ec0 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c  * that the suppl
25ed0 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75  ied string is nu
25ee0 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68  l-terminated, th
25ef0 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d  en there is a sm
25f00 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e  all.** performan
25f10 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20  ce advantage to 
25f20 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73  be gained by pas
25f30 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61  sing an nByte pa
25f40 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20  rameter that.** 
25f50 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  is equal to the 
25f60 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
25f70 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  in the input str
25f80 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67  ing <i>including
25f90 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d  </i>.** the nul-
25fa0 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73  terminator bytes
25fb0 20 61 73 20 74 68 69 73 20 73 61 76 65 73 20 53   as this saves S
25fc0 51 4c 69 74 65 20 66 72 6f 6d 20 68 61 76 69 6e  QLite from havin
25fd0 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63  g to.** make a c
25fe0 6f 70 79 20 6f 66 20 74 68 65 20 69 6e 70 75 74  opy of the input
25ff0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e   string..**.** ^
26000 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74  If pzTail is not
26010 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61   NULL then *pzTa
26020 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  il is made to po
26030 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74  int to the first
26040 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68   byte.** past th
26050 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72  e end of the fir
26060 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
26070 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65   in zSql.  These
26080 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a   routines only.*
26090 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69  * compile the fi
260a0 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  rst statement in
260b0 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69   zSql, so *pzTai
260c0 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  l is left pointi
260d0 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65  ng to.** what re
260e0 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64  mains uncompiled
260f0 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74  ..**.** ^*ppStmt
26100 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
26110 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20  g to a compiled 
26120 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26130 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65  ent] that can be
26140 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69  .** executed usi
26150 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
26160 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20  ()].  ^If there 
26170 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70  is an error, *pp
26180 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74  Stmt is set.** t
26190 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65  o NULL.  ^If the
261a0 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74   input text cont
261b0 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20  ains no SQL (if 
261c0 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20  the input is an 
261d0 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20  empty.** string 
261e0 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68  or a comment) th
261f0 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  en *ppStmt is se
26200 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68  t to NULL..** Th
26210 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64  e calling proced
26220 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ure is responsib
26230 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20  le for deleting 
26240 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  the compiled.** 
26250 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73  SQL statement us
26260 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
26270 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69  alize()] after i
26280 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  t has finished w
26290 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d  ith it..** ppStm
262a0 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c  t may not be NUL
262b0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63  L..**.** ^On suc
262c0 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65  cess, the sqlite
262d0 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69  3_prepare() fami
262e0 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72  ly of routines r
262f0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
26300 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20  ];.** otherwise 
26310 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
26320 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
26330 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  ** The sqlite3_p
26340 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20  repare_v2() and 
26350 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
26360 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  6_v2() interface
26370 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65  s are.** recomme
26380 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77  nded for all new
26390 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74   programs. The t
263a0 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61  wo older interfa
263b0 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64  ces are retained
263c0 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64  .** for backward
263d0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c  s compatibility,
263e0 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69   but their use i
263f0 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a  s discouraged..*
26400 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69  * ^In the "v2" i
26410 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70  nterfaces, the p
26420 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26430 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74  t.** that is ret
26440 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69  urned (the [sqli
26450 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
26460 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70  ) contains a cop
26470 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67  y of the.** orig
26480 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54  inal SQL text. T
26490 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b  his causes the [
264a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
264b0 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20  interface to.** 
264c0 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74  behave different
264d0 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73  ly in three ways
264e0 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
264f0 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
26500 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
26510 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64  changes, instead
26520 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53   of returning [S
26530 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73  QLITE_SCHEMA] as
26540 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73   it.** always us
26550 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74  ed to do, [sqlit
26560 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
26570 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
26580 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a  compile the SQL.
26590 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ** statement and
265a0 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61   try to run it a
265b0 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73  gain. As many as
265c0 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48   [SQLITE_MAX_SCH
265d0 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65  EMA_RETRY].** re
265e0 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72  tries will occur
265f0 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
26600 73 74 65 70 28 29 20 67 69 76 65 73 20 75 70 20  step() gives up 
26610 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65  and returns an e
26620 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  rror..** </li>.*
26630 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68  *.** <li>.** ^Wh
26640 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  en an error occu
26650 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  rs, [sqlite3_ste
26660 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  p()] will return
26670 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61   one of the deta
26680 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  iled.** [error c
26690 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64  odes] or [extend
266a0 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e  ed error codes].
266b0 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65    ^The legacy be
266c0 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a  havior was that.
266d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
266e0 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72  ()] would only r
266f0 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20  eturn a generic 
26700 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72  [SQLITE_ERROR] r
26710 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e  esult code.** an
26720 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
26730 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20  n would have to 
26740 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61  make a second ca
26750 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ll to [sqlite3_r
26760 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72  eset()].** in or
26770 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20  der to find the 
26780 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65  underlying cause
26790 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e   of the problem.
267a0 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70   With the "v2" p
267b0 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66  repare.** interf
267c0 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c  aces, the underl
267d0 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20  ying reason for 
267e0 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74  the error is ret
267f0 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
26800 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  y..** </li>.**.*
26810 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
26820 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65  e specific value
26830 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d   bound to [param
26840 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61  eter | host para
26850 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a  meter] in the .*
26860 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d  * WHERE clause m
26870 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
26880 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  he choice of que
26890 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74  ry plan for a st
268a0 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e  atement,.** then
268b0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
268c0 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
268d0 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c  ally recompiled,
268e0 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64   as if there had
268f0 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65   been .** a sche
26900 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68  ma change, on th
26910 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65  e first  [sqlite
26920 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66  3_step()] call f
26930 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61  ollowing any cha
26940 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  nge.** to the [s
26950 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
26960 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20   | bindings] of 
26970 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d  that [parameter]
26980 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69  . .** ^The speci
26990 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45  fic value of WHE
269a0 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d  RE-clause [param
269b0 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c  eter] might infl
269c0 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68  uence the .** ch
269d0 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
269e0 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  an if the parame
269f0 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d  ter is the left-
26a00 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b  hand side of a [
26a10 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f  LIKE].** or [GLO
26a20 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69  B] operator or i
26a30 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
26a40 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61  is compared to a
26a50 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e  n indexed column
26a60 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c  .** and the [SQL
26a70 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33  ITE_ENABLE_STAT3
26a80 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
26a90 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ption is enabled
26aa0 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  ..** </li>.** </
26ab0 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ol>.*/.int sqlit
26ac0 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71  e3_prepare(.  sq
26ad0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
26ae0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
26af0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
26b00 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
26b10 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
26b20 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
26b30 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
26b40 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
26b50 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
26b60 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
26b70 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
26b80 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
26b90 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
26ba0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
26bb0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
26bc0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
26bd0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
26be0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
26bf0 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
26c00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
26c10 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
26c20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
26c30 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
26c40 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
26c50 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
26c60 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
26c70 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
26c80 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
26c90 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
26ca0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
26cb0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
26cc0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
26cd0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
26ce0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
26cf0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
26d00 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
26d10 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
26d20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
26d30 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
26d40 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
26d50 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33  are16(.  sqlite3
26d60 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
26d70 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
26d80 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
26d90 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
26da0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
26db0 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
26dc0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
26dd0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
26de0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
26df0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
26e00 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
26e10 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
26e20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
26e30 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
26e40 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
26e50 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
26e60 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
26e70 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
26e80 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
26e90 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a  3_prepare16_v2(.
26ea0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
26eb0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
26ec0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
26ed0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
26ee0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
26ef0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
26f00 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
26f10 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
26f20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
26f30 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
26f40 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
26f50 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
26f60 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
26f70 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
26f80 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
26f90 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
26fa0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
26fb0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
26fc0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a   of zSql */.);..
26fd0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
26fe0 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65  Retrieving State
26ff0 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e  ment SQL.**.** ^
27000 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
27010 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
27020 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63  trieve a saved c
27030 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69  opy of the origi
27040 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20  nal.** SQL text 
27050 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61  used to create a
27060 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
27070 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74  ment] if that st
27080 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63  atement was.** c
27090 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69  ompiled using ei
270a0 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
270b0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
270c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
270d0 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  6_v2()]..*/.cons
270e0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
270f0 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  sql(sqlite3_stmt
27100 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
27110 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
27120 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
27130 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20  tatement Writes 
27140 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a  The Database.**.
27150 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
27160 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29  stmt_readonly(X)
27170 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
27180 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
27190 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c  o) if.** and onl
271a0 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72  y if the [prepar
271b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20  ed statement] X 
271c0 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20  makes no direct 
271d0 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68  changes to.** th
271e0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
271f0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a   database file..
27200 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
27210 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
27220 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
27230 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75  ns] or.** [virtu
27240 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74  al tables] might
27250 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
27260 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20  base indirectly 
27270 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74  as a side effect
27280 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .  .** ^(For exa
27290 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c  mple, if an appl
272a0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20  ication defines 
272b0 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c  a function "eval
272c0 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c  ()" that .** cal
272d0 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ls [sqlite3_exec
272e0 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  ()], then the fo
272f0 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74  llowing SQL stat
27300 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63  ement would.** c
27310 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
27320 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20  se file through 
27330 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a  side-effects:.**
27340 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
27350 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45  <pre>.**    SELE
27360 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20  CT eval('DELETE 
27370 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74  FROM t1') FROM t
27380 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  2;.** </pre></bl
27390 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
273a0 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20  But because the 
273b0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
273c0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nt does not chan
273d0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
273e0 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79  file.** directly
273f0 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  , sqlite3_stmt_r
27400 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20  eadonly() would 
27410 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75  still return tru
27420 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e  e.)^.**.** ^Tran
27430 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20  saction control 
27440 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20  statements such 
27450 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d  as [BEGIN], [COM
27460 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d  MIT], [ROLLBACK]
27470 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d  ,.** [SAVEPOINT]
27480 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20  , and [RELEASE] 
27490 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74  cause sqlite3_st
274a0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
274b0 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a   return true,.**
274c0 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65   since the state
274d0 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73  ments themselves
274e0 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79   do not actually
274f0 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
27500 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68  base but.** rath
27510 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20  er they control 
27520 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68  the timing of wh
27530 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65  en other stateme
27540 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a  nts modify the .
27550 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54  ** database.  ^T
27560 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20  he [ATTACH] and 
27570 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65  [DETACH] stateme
27580 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a  nts also cause.*
27590 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  * sqlite3_stmt_r
275a0 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
275b0 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20  urn true since, 
275c0 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74  while those stat
275d0 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65  ements.** change
275e0 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
275f0 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65  on of a database
27600 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65   connection, the
27610 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a  y do not make .*
27620 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  * changes to the
27630 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
27640 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f  database files o
27650 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73  n disk..*/.int s
27660 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
27670 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  only(sqlite3_stm
27680 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
27690 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
276a0 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70 61  rmine If A Prepa
276b0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61  red Statement Ha
276c0 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 0a  s Been Reset.**.
276d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
276e0 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74  stmt_busy(S) int
276f0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
27700 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69  rue (non-zero) i
27710 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  f the.** [prepar
27720 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
27730 68 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64  has been stepped
27740 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75   at least once u
27750 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
27760 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68  3_step(S)] but h
27770 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20 63 6f  as not run to co
27780 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f 72 20  mpletion and/or 
27790 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e  has not .** been
277a0 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71   reset using [sq
277b0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e  lite3_reset(S)].
277c0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
277d0 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69  tmt_busy(S).** i
277e0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
277f0 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 61   false if S is a
27800 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
27810 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a  If S is not a .*
27820 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  * NULL pointer a
27830 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e  nd is not a poin
27840 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b  ter to a valid [
27850 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27860 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74  nt].** object, t
27870 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
27880 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
27890 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73  d probably undes
278a0 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  irable..**.** Th
278b0 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
278c0 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62   be used in comb
278d0 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33  ination [sqlite3
278e0 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a  _next_stmt()].**
278f0 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70   to locate all p
27900 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27910 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ts associated wi
27920 74 68 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a  th a database .*
27930 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  * connection tha
27940 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66  t are in need of
27950 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54   being reset.  T
27960 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c  his can be used,
27970 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  .** for example,
27980 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72   in diagnostic r
27990 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63  outines to searc
279a0 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a  h for prepared .
279b0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  ** statements th
279c0 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61  at are holding a
279d0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65   transaction ope
279e0 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
279f0 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69  3_stmt_busy(sqli
27a00 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
27a10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e  ** CAPI3REF: Dyn
27a20 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56  amically Typed V
27a30 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  alue Object.** K
27a40 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63  EYWORDS: {protec
27a50 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
27a60 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20  e} {unprotected 
27a70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a  sqlite3_value}.*
27a80 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
27a90 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
27aa0 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70  ue object to rep
27ab0 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65  resent all value
27ac0 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
27ad0 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74   stored in a dat
27ae0 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c  abase table. SQL
27af0 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
27b00 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74   typing.** for t
27b10 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f  he values it sto
27b20 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74  res.  ^Values st
27b30 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f  ored in sqlite3_
27b40 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a  value objects.**
27b50 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73   can be integers
27b60 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  , floating point
27b70 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73   values, strings
27b80 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c  , BLOBs, or NULL
27b90 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74  ..**.** An sqlit
27ba0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
27bb0 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70  may be either "p
27bc0 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e  rotected" or "un
27bd0 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53  protected"..** S
27be0 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72  ome interfaces r
27bf0 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74  equire a protect
27c00 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
27c10 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61  .  Other interfa
27c20 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65  ces.** will acce
27c30 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74  pt either a prot
27c40 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72  ected or an unpr
27c50 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
27c60 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20  value..** Every 
27c70 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
27c80 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76  ccepts sqlite3_v
27c90 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73  alue arguments s
27ca0 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74  pecifies.** whet
27cb0 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65  her or not it re
27cc0 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74  quires a protect
27cd0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
27ce0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d  ..**.** The term
27cf0 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e  s "protected" an
27d00 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20  d "unprotected" 
27d10 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72  refer to whether
27d20 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74   or not.** a mut
27d30 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20  ex is held.  An 
27d40 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69  internal mutex i
27d50 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f  s held for a pro
27d60 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
27d70 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62  3_value object b
27d80 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68  ut no mutex is h
27d90 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f  eld for an unpro
27da0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
27db0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20  3_value object. 
27dc0 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
27dd0 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e  mpiled to be sin
27de0 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  gle-threaded.** 
27df0 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48  (with [SQLITE_TH
27e00 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20  READSAFE=0] and 
27e10 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68  with [sqlite3_th
27e20 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75  readsafe()] retu
27e30 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69  rning 0).** or i
27e40 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20  f SQLite is run 
27e50 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65  in one of reduce
27e60 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a  d mutex modes .*
27e70 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
27e80 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f  _SINGLETHREAD] o
27e90 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
27ea0 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a  _MULTITHREAD].**
27eb0 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e   then there is n
27ec0 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  o distinction be
27ed0 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
27ee0 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
27ef0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
27f00 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65   objects and the
27f10 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  y can be used in
27f20 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20  terchangeably.  
27f30 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20  However,.** for 
27f40 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72  maximum code por
27f50 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72  tability it is r
27f60 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
27f70 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
27f80 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64  still make the d
27f90 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
27fa0 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
27fb0 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
27fc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
27fd0 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20  jects even when 
27fe0 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71  not strictly req
27ff0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  uired..**.** ^Th
28000 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
28010 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65  objects that are
28020 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d   passed as param
28030 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a  eters into the.*
28040 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
28050 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   of [application
28060 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
28070 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74  ctions] are prot
28080 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  ected..** ^The s
28090 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
280a0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
280b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
280c0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
280d0 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55  nprotected..** U
280e0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
280f0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
28100 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
28110 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74  d with.** [sqlit
28120 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
28130 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
28140 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  bind_value()]..*
28150 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  * The [sqlite3_v
28160 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  alue_blob | sqli
28170 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29  te3_value_type()
28180 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69  ] family of.** i
28190 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
281a0 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  e protected sqli
281b0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
281c0 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
281d0 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33  ruct Mem sqlite3
281e0 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
281f0 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e  API3REF: SQL Fun
28200 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62  ction Context Ob
28210 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ject.**.** The c
28220 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20  ontext in which 
28230 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
28240 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72  executes is stor
28250 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ed in an.** sqli
28260 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
28270 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20  ct.  ^A pointer 
28280 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f  to an sqlite3_co
28290 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20  ntext object.** 
282a0 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20  is always first 
282b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70  parameter to [ap
282c0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
282d0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
282e0 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
282f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
28300 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
28310 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61  entation will pa
28320 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74  ss this.** point
28330 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20  er through into 
28340 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
28350 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73  3_result_int | s
28360 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d  qlite3_result()]
28370 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67  ,.** [sqlite3_ag
28380 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
28390 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  )], [sqlite3_use
283a0 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73  r_data()],.** [s
283b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
283c0 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71  b_handle()], [sq
283d0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
283e0 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20  a()],.** and/or 
283f0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
28400 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  data()]..*/.type
28410 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
28420 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74  e3_context sqlit
28430 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a  e3_context;../*.
28440 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e  ** CAPI3REF: Bin
28450 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50  ding Values To P
28460 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
28470 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ts.** KEYWORDS: 
28480 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d  {host parameter}
28490 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
284a0 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  s} {host paramet
284b0 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57  er name}.** KEYW
284c0 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d  ORDS: {SQL param
284d0 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d  eter} {SQL param
284e0 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65  eters} {paramete
284f0 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a  r binding}.**.**
28500 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74   ^(In the SQL st
28510 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70  atement text inp
28520 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ut to [sqlite3_p
28530 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
28540 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a   its variants,.*
28550 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62  * literals may b
28560 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  e replaced by a 
28570 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74  [parameter] that
28580 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20   matches one of 
28590 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d  following.** tem
285a0 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  plates:.**.** <u
285b0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a  l>.** <li>  ?.**
285c0 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c   <li>  ?NNN.** <
285d0 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69  li>  :VVV.** <li
285e0 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  @VVV.** <li> 
285f0 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a   $VVV.** </ul>.*
28600 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70  *.** In the temp
28610 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e  lates above, NNN
28620 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69   represents an i
28630 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a  nteger literal,.
28640 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65  ** and VVV repre
28650 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75  sents an alphanu
28660 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72  meric identifier
28670 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  .)^  ^The values
28680 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72   of these.** par
28690 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61  ameters (also ca
286a0 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d  lled "host param
286b0 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22  eter names" or "
286c0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29  SQL parameters")
286d0 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75  .** can be set u
286e0 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
286f0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
28700 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  es defined here.
28710 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
28720 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
28730 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
28740 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61  () routines is a
28750 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  lways.** a point
28760 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
28770 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20  e3_stmt] object 
28780 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a  returned from.**
28790 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
287a0 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76  e_v2()] or its v
287b0 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ariants..**.** ^
287c0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
287d0 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
287e0 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61   of the SQL para
287f0 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e  meter to be set.
28800 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  .** ^The leftmos
28810 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  t SQL parameter 
28820 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
28830 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61  1.  ^When the sa
28840 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20  me named.** SQL 
28850 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65  parameter is use
28860 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  d more than once
28870 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  , second and sub
28880 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72  sequent.** occur
28890 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20  rences have the 
288a0 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68  same index as th
288b0 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e  e first occurren
288c0 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65  ce..** ^The inde
288d0 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61  x for named para
288e0 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f  meters can be lo
288f0 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68  oked up using th
28900 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  e.** [sqlite3_bi
28910 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
28920 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73  ex()] API if des
28930 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65  ired.  ^The inde
28940 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20  x.** for "?NNN" 
28950 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68  parameters is th
28960 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a  e value of NNN..
28970 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75  ** ^The NNN valu
28980 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65  e must be betwee
28990 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c  n 1 and the [sql
289a0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
289b0 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49   parameter [SQLI
289c0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
289d0 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75  E_NUMBER] (defau
289e0 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a  lt value: 999)..
289f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
28a00 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
28a10 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74   value to bind t
28a20 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  o the parameter.
28a30 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72  .** ^If the thir
28a40 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
28a50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
28a60 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  () or sqlite3_bi
28a70 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f  nd_text16().** o
28a80 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  r sqlite3_bind_b
28a90 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20  lob() is a NULL 
28aa0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
28ab0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
28ac0 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20  r.** is ignored 
28ad0 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73 75  and the end resu
28ae0 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65 20 61  lt is the same a
28af0 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  s sqlite3_bind_n
28b00 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  ull()..**.** ^(I
28b10 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73  n those routines
28b20 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75   that have a fou
28b30 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74  rth argument, it
28b40 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  s value is the.*
28b50 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  * number of byte
28b60 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  s in the paramet
28b70 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72  er.  To be clear
28b80 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74  : the value is t
28b90 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
28ba0 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20  <u>bytes</u> in 
28bb0 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74  the value, not t
28bc0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
28bd0 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49  racters.)^.** ^I
28be0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
28bf0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
28c00 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72  3_bind_text() or
28c10 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
28c20 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67  xt16().** is neg
28c30 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
28c40 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74  length of the st
28c50 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e  ring is.** the n
28c60 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75  umber of bytes u
28c70 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
28c80 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
28c90 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  ** If the fourth
28ca0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
28cb0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
28cc0 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  ) is negative, t
28cd0 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76  hen.** the behav
28ce0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
28cf0 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65  ..** If a non-ne
28d00 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61  gative fourth pa
28d10 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69  rameter is provi
28d20 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ded to sqlite3_b
28d30 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72  ind_text().** or
28d40 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
28d50 78 74 31 36 28 29 20 74 68 65 6e 20 74 68 61 74  xt16() then that
28d60 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
28d70 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73  be the byte offs
28d80 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20  et.** where the 
28d90 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
28da0 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d  ould occur assum
28db0 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77  ing the string w
28dc0 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69  ere NUL.** termi
28dd0 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e  nated.  If any N
28de0 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63  UL characters oc
28df0 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73  cur at byte offs
28e00 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a  ets less than .*
28e10 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * the value of t
28e20 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
28e30 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73  ter then the res
28e40 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61  ulting string va
28e50 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74  lue will.** cont
28e60 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
28e70 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f  s.  The result o
28e80 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e  f expressions in
28e90 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a  volving strings.
28ea0 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64  ** with embedded
28eb0 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e   NULs is undefin
28ec0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
28ed0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ifth argument to
28ee0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
28ef0 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69  ob(), sqlite3_bi
28f00 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a  nd_text(), and.*
28f10 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  * sqlite3_bind_t
28f20 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73  ext16() is a des
28f30 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20  tructor used to 
28f40 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
28f50 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67  LOB or.** string
28f60 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61   after SQLite ha
28f70 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
28f80 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75  it.  ^The destru
28f90 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a  ctor is called.*
28fa0 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  * to dispose of 
28fb0 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  the BLOB or stri
28fc0 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63  ng even if the c
28fd0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  all to sqlite3_b
28fe0 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73  ind_blob(),.** s
28ff0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
29000 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  (), or sqlite3_b
29010 69 6e 64 5f 74 65 78 74 31 36 28 29 20 66 61 69  ind_text16() fai
29020 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65  ls.  .** ^If the
29030 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
29040 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61  is.** the specia
29050 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  l value [SQLITE_
29060 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51  STATIC], then SQ
29070 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
29080 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  t the.** informa
29090 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69  tion is in stati
290a0 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61  c, unmanaged spa
290b0 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  ce and does not 
290c0 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64  need to be freed
290d0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66  ..** ^If the fif
290e0 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20  th argument has 
290f0 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  the value [SQLIT
29100 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68  E_TRANSIENT], th
29110 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b  en.** SQLite mak
29120 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  es its own priva
29130 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64  te copy of the d
29140 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c  ata immediately,
29150 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73   before.** the s
29160 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
29170 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e  routine returns.
29180 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
29190 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
291a0 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64  b() routine bind
291b0 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67  s a BLOB of leng
291c0 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20  th N that.** is 
291d0 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f  filled with zero
291e0 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62  es.  ^A zeroblob
291f0 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d   uses a fixed am
29200 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ount of memory.*
29210 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67  * (just an integ
29220 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73  er to hold its s
29230 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73  ize) while it is
29240 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64   being processed
29250 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61  ..** Zeroblobs a
29260 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73  re intended to s
29270 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c  erve as placehol
29280 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77  ders for BLOBs w
29290 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20  hose.** content 
292a0 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e  is later written
292b0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
292c0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
292d0 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
292e0 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  I/O] routines..*
292f0 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61  * ^A negative va
29300 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f  lue for the zero
29310 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20  blob results in 
29320 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
29330 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  OB..**.** ^If an
29340 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  y of the sqlite3
29350 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
29360 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69  es are called wi
29370 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
29380 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72  r.** for the [pr
29390 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
293a0 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70  ] or with a prep
293b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66  ared statement f
293c0 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c  or which.** [sql
293d0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
293e0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72   been called mor
293f0 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20  e recently than 
29400 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
29410 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  ],.** then the c
29420 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  all will return 
29430 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
29440 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33    If any sqlite3
29450 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74  _bind_().** rout
29460 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20  ine is passed a 
29470 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29480 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65  ent] that has be
29490 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68  en finalized, th
294a0 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75  e.** result is u
294b0 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
294c0 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a  bably harmful..*
294d0 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61  *.** ^Bindings a
294e0 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62  re not cleared b
294f0 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  y the [sqlite3_r
29500 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e  eset()] routine.
29510 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72  .** ^Unbound par
29520 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65  ameters are inte
29530 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e  rpreted as NULL.
29540 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
29550 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69  te3_bind_* routi
29560 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
29570 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
29580 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f  s or an.** [erro
29590 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68  r code] if anyth
295a0 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a  ing goes wrong..
295b0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47  ** ^[SQLITE_RANG
295c0 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  E] is returned i
295d0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a  f the parameter.
295e0 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  ** index is out 
295f0 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c  of range.  ^[SQL
29600 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65  ITE_NOMEM] is re
29610 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63  turned if malloc
29620 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20  () fails..**.** 
29630 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
29640 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
29650 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b  r_count()],.** [
29660 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
29670 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
29680 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
29690 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
296a0 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  x()]..*/.int sql
296b0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73  ite3_bind_blob(s
296c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
296d0 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
296e0 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76  int n, void(*)(v
296f0 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
29700 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28  te3_bind_double(
29710 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
29720 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74  nt, double);.int
29730 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
29740 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
29750 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20   int, int);.int 
29760 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
29770 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
29780 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69  , int, sqlite3_i
29790 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74  nt64);.int sqlit
297a0 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c  e3_bind_null(sql
297b0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
297c0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
297d0 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  nd_text(sqlite3_
297e0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
297f0 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20  t char*, int n, 
29800 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
29810 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
29820 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  d_text16(sqlite3
29830 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
29840 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
29850 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
29860 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
29870 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
29880 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
29890 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
298a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
298b0 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  nd_zeroblob(sqli
298c0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
298d0 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
298e0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
298f0 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72  Of SQL Parameter
29900 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  s.**.** ^This ro
29910 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65  utine can be use
29920 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
29930 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72  mber of [SQL par
29940 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61  ameters].** in a
29950 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29960 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61  ment].  SQL para
29970 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e  meters are token
29980 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d  s of the.** form
29990 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a   "?", "?NNN", ":
299a0 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72  AAA", "$AAA", or
299b0 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72   "@AAA" that ser
299c0 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f  ve as.** placeho
299d0 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73  lders for values
299e0 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74   that are [sqlit
299f0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
29a00 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  ound].** to the 
29a10 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20  parameters at a 
29a20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  later time..**.*
29a30 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
29a40 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e   actually return
29a50 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
29a60 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68  he largest (righ
29a70 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65  tmost).** parame
29a80 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72  ter. For all for
29a90 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20  ms except ?NNN, 
29aa0 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73  this will corres
29ab0 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e  pond to the.** n
29ac0 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20  umber of unique 
29ad0 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20  parameters.  If 
29ae0 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
29af0 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20  e ?NNN form are 
29b00 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d  used,.** there m
29b10 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68  ay be gaps in th
29b20 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  e list.)^.**.** 
29b30 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
29b40 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
29b50 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
29b60 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
29b70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
29b80 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
29b90 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
29ba0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
29bb0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
29bc0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73  arameter_count(s
29bd0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
29be0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29bf0 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50  Name Of A Host P
29c00 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e  arameter.**.** ^
29c10 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
29c20 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
29c30 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72  P,N) interface r
29c40 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61  eturns.** the na
29c50 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b  me of the N-th [
29c60 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69  SQL parameter] i
29c70 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
29c80 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a  statement] P..**
29c90 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72   ^(SQL parameter
29ca0 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
29cb0 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
29cc0 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
29cd0 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d  A".** have a nam
29ce0 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73  e which is the s
29cf0 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20  tring "?NNN" or 
29d00 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
29d10 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65   or "$AAA".** re
29d20 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49  spectively..** I
29d30 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
29d40 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f  he initial ":" o
29d50 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20  r "$" or "@" or 
29d60 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64  "?".** is includ
29d70 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
29d80 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61  e name.)^.** ^Pa
29d90 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
29da0 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74  form "?" without
29db0 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74   a following int
29dc0 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d  eger have no nam
29dd0 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66  e.** and are ref
29de0 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d  erred to as "nam
29df0 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79  eless" or "anony
29e00 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22  mous parameters"
29e10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
29e20 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  st host paramete
29e30 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
29e40 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a  f 1, not 0..**.*
29e50 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20  * ^If the value 
29e60 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
29e70 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68  e or if the N-th
29e80 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
29e90 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20   nameless, then 
29ea0 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64  NULL is returned
29eb0 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  .  ^The returned
29ec0 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c   string is.** al
29ed0 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e  ways in UTF-8 en
29ee0 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74  coding even if t
29ef0 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  he named paramet
29f00 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e  er was.** origin
29f10 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61  ally specified a
29f20 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c  s UTF-16 in [sql
29f30 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
29f40 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
29f50 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
29f60 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
29f70 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
29f80 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
29f90 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
29fa0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
29fb0 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
29fc0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
29fd0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
29fe0 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  )]..*/.const cha
29ff0 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  r *sqlite3_bind_
2a000 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73  parameter_name(s
2a010 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2a020 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2a030 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20  REF: Index Of A 
2a040 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41  Parameter With A
2a050 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a   Given Name.**.*
2a060 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e  * ^Return the in
2a070 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  dex of an SQL pa
2a080 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74  rameter given it
2a090 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a  s name.  ^The.**
2a0a0 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74   index value ret
2a0b0 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c  urned is suitabl
2a0c0 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65  e for use as the
2a0d0 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d   second.** param
2a0e0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
2a0f0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
2a100 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20  e3_bind()].  ^A 
2a110 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72  zero.** is retur
2a120 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69  ned if no matchi
2a130 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ng parameter is 
2a140 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72  found.  ^The par
2a150 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d  ameter.** name m
2a160 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20  ust be given in 
2a170 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68  UTF-8 even if th
2a180 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
2a190 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70  ment.** was prep
2a1a0 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36  ared from UTF-16
2a1b0 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c   text using [sql
2a1c0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2a1d0 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
2a1e0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2a1f0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
2a200 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
2a210 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2a220 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
2a230 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
2a240 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2a250 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
2a260 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2a270 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69  meter_index(sqli
2a280 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74  te3_stmt*, const
2a290 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a   char *zName);..
2a2a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2a2b0 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e  Reset All Bindin
2a2c0 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64  gs On A Prepared
2a2d0 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
2a2e0 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68   ^Contrary to th
2a2f0 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d  e intuition of m
2a300 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  any, [sqlite3_re
2a310 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20  set()] does not 
2a320 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71  reset.** the [sq
2a330 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
2a340 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61  | bindings] on a
2a350 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2a360 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74  ment]..** ^Use t
2a370 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72  his routine to r
2a380 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61  eset all host pa
2a390 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c  rameters to NULL
2a3a0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2a3b0 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
2a3c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2a3d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2a3e0 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d   Number Of Colum
2a3f0 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  ns In A Result S
2a400 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  et.**.** ^Return
2a410 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
2a420 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
2a430 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65  sult set returne
2a440 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65  d by the.** [pre
2a450 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a460 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  . ^This routine 
2a470 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74  returns 0 if pSt
2a480 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20  mt is an SQL.** 
2a490 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64  statement that d
2a4a0 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64  oes not return d
2a4b0 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ata (for example
2a4c0 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a   an [UPDATE])..*
2a4d0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2a4e0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2a4f0 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nt()].*/.int sql
2a500 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
2a510 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
2a520 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2a530 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20  API3REF: Column 
2a540 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c  Names In A Resul
2a550 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  t Set.**.** ^The
2a560 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
2a570 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69  rn the name assi
2a580 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63  gned to a partic
2a590 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  ular column.** i
2a5a0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
2a5b0 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   of a [SELECT] s
2a5c0 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20  tatement.  ^The 
2a5d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2a5e0 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ame().** interfa
2a5f0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2a600 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
2a610 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
2a620 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71  string.** and sq
2a630 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2a640 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20  e16() returns a 
2a650 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
2a660 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
2a670 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
2a680 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
2a690 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65  eter is the [pre
2a6a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a6b0 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  .** that impleme
2a6c0 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  nts the [SELECT]
2a6d0 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65   statement. ^The
2a6e0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2a6f0 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r is the.** colu
2a700 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65  mn number.  ^The
2a710 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
2a720 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a   is number 0..**
2a730 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
2a740 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  d string pointer
2a750 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
2a760 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70  either the [prep
2a770 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
2a780 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20  ** is destroyed 
2a790 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  by [sqlite3_fina
2a7a0 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
2a7b0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2a7c0 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  s automatically.
2a7d0 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79  ** reprepared by
2a7e0 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
2a7f0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2a800 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63  ()] for a partic
2a810 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75  ular run.** or u
2a820 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61  ntil the next ca
2a830 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ll to.** sqlite3
2a840 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f  _column_name() o
2a850 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
2a860 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65  _name16() on the
2a870 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a   same column..**
2a880 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
2a890 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64  malloc() fails d
2a8a0 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73  uring the proces
2a8b0 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72  sing of either r
2a8c0 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65  outine.** (for e
2a8d0 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20  xample during a 
2a8e0 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20  conversion from 
2a8f0 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29  UTF-8 to UTF-16)
2a900 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20   then a.** NULL 
2a910 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
2a920 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2a930 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74  name of a result
2a940 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76   column is the v
2a950 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22  alue of the "AS"
2a960 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74   clause for.** t
2a970 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74  hat column, if t
2a980 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c  here is an AS cl
2a990 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20  ause.  If there 
2a9a0 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a  is no AS clause.
2a9b0 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65  ** then the name
2a9c0 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
2a9d0 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e  s unspecified an
2a9e0 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f  d may change fro
2a9f0 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65  m.** one release
2aa00 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68   of SQLite to th
2aa10 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74  e next..*/.const
2aa20 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2aa30 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  olumn_name(sqlit
2aa40 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
2aa50 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2aa60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2aa70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2aa80 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a  *, int N);../*.*
2aa90 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72  * CAPI3REF: Sour
2aaa0 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20  ce Of Data In A 
2aab0 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a  Query Result.**.
2aac0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
2aad0 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61  es provide a mea
2aae0 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ns to determine 
2aaf0 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61  the database, ta
2ab00 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c  ble, and.** tabl
2ab10 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73  e column that is
2ab20 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61   the origin of a
2ab30 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75   particular resu
2ab40 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20  lt column in.** 
2ab50 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2ab60 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  nt..** ^The name
2ab70 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2ab80 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c   or table or col
2ab90 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72  umn can be retur
2aba0 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72  ned as.** either
2abb0 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d   a UTF-8 or UTF-
2abc0 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
2abd0 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74   _database_ rout
2abe0 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74  ines return.** t
2abf0 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
2ac00 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f  , the _table_ ro
2ac10 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
2ac20 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e  e table name, an
2ac30 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f  d.** the origin_
2ac40 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2ac50 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   the column name
2ac60 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
2ac70 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c  ed string is val
2ac80 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72  id until the [pr
2ac90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2aca0 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a  ] is destroyed.*
2acb0 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
2acc0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
2acd0 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
2ace0 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
2acf0 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
2ad00 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
2ad10 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2ad20 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
2ad30 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
2ad40 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61   or until the sa
2ad50 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  me information i
2ad60 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61  s requested.** a
2ad70 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72  gain in a differ
2ad80 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ent encoding..**
2ad90 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72  .** ^The names r
2ada0 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20  eturned are the 
2adb0 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61  original un-alia
2adc0 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  sed names of the
2add0 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61  .** database, ta
2ade0 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e  ble, and column.
2adf0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
2ae00 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
2ae10 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69  ese interfaces i
2ae20 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
2ae30 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68  atement]..** ^Th
2ae40 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
2ae50 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
2ae60 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72   about the Nth r
2ae70 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74  esult column ret
2ae80 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  urned by.** the 
2ae90 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65  statement, where
2aea0 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
2aeb0 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
2aec0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  nt..** ^The left
2aed0 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  -most column is 
2aee0 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65  column 0 for the
2aef0 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
2af00 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ** ^If the Nth c
2af10 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
2af20 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  y the statement 
2af30 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e  is an expression
2af40 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20   or.** subquery 
2af50 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c  and is not a col
2af60 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  umn value, then 
2af70 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e  all of these fun
2af80 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a  ctions return.**
2af90 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72   NULL.  ^These r
2afa0 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73  outine might als
2afb0 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66  o return NULL if
2afc0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
2afd0 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63  tion error.** oc
2afe0 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73  curs.  ^Otherwis
2aff0 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74  e, they return t
2b000 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61  he name of the a
2b010 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
2b020 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63  , table,.** or c
2b030 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79  olumn that query
2b040 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77   result column w
2b050 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f  as extracted fro
2b060 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74  m..**.** ^As wit
2b070 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69  h all other SQLi
2b080 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77  te APIs, those w
2b090 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77  hose names end w
2b0a0 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a  ith "16" return.
2b0b0 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  ** UTF-16 encode
2b0c0 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68  d strings and th
2b0d0 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  e other function
2b0e0 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a  s return UTF-8..
2b0f0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49  **.** ^These API
2b100 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c  s are only avail
2b110 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
2b120 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
2b130 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
2b140 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
2b150 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70  MN_METADATA] C-p
2b160 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
2b170 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ol..**.** If two
2b180 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
2b190 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
2b1a0 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
2b1b0 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20  nes against the 
2b1c0 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64  same.** prepared
2b1d0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63   statement and c
2b1e0 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d  olumn at the sam
2b1f0 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
2b200 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75  results are.** u
2b210 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2b220 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
2b230 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
2b240 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69  or more.** [sqli
2b250 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
2b260 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d  ase_name | colum
2b270 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72  n metadata inter
2b280 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68  faces].** for th
2b290 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  e same [prepared
2b2a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20   statement] and 
2b2b0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  result column.**
2b2c0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
2b2d0 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
2b2e0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
2b2f0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
2b300 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2b310 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71  database_name(sq
2b320 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2b330 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2b340 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
2b350 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c  abase_name16(sql
2b360 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2b370 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
2b380 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
2b390 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
2b3a0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
2b3b0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2b3c0 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
2b3d0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2b3e0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
2b3f0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2b400 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71  n_origin_name(sq
2b410 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2b420 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2b430 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
2b440 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  gin_name16(sqlit
2b450 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
2b460 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2b470 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70  Declared Datatyp
2b480 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73  e Of A Query Res
2b490 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ult.**.** ^(The 
2b4a0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2b4b0 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
2b4c0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66  tatement]..** If
2b4d0 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20   this statement 
2b4e0 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  is a [SELECT] st
2b4f0 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20  atement and the 
2b500 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
2b510 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65  e.** returned re
2b520 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74  sult set of that
2b530 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74   [SELECT] is a t
2b540 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74  able column (not
2b550 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
2b560 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74  n or subquery) t
2b570 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64  hen the declared
2b580 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62   type of the tab
2b590 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20  le.** column is 
2b5a0 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66  returned.)^  ^If
2b5b0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
2b5c0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2b5d0 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65  t is an.** expre
2b5e0 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
2b5f0 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70  y, then a NULL p
2b600 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
2b610 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  ed..** ^The retu
2b620 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61  rned string is a
2b630 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f  lways UTF-8 enco
2b640 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72  ded..**.** ^(For
2b650 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20   example, given 
2b660 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
2b670 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54  ema:.**.** CREAT
2b680 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41  E TABLE t1(c1 VA
2b690 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e  RIANT);.**.** an
2b6a0 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  d the following 
2b6b0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
2b6c0 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20  compiled:.**.** 
2b6d0 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63  SELECT c1 + 1, c
2b6e0 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a  1 FROM t1;.**.**
2b6f0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f   this routine wo
2b700 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73  uld return the s
2b710 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20  tring "VARIANT" 
2b720 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72  for the second r
2b730 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  esult.** column 
2b740 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55  (i==1), and a NU
2b750 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  LL pointer for t
2b760 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20  he first result 
2b770 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e  column (i==0).)^
2b780 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
2b790 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d  ses dynamic run-
2b7a0 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53  time typing.  ^S
2b7b0 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61  o just because a
2b7c0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65   column.** is de
2b7d0 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69  clared to contai
2b7e0 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74  n a particular t
2b7f0 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61  ype does not mea
2b800 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61  n that the.** da
2b810 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61  ta stored in tha
2b820 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74  t column is of t
2b830 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
2b840 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  .  SQLite is.** 
2b850 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20  strongly typed, 
2b860 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69  but the typing i
2b870 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74  s dynamic not st
2b880 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20  atic.  ^Type.** 
2b890 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
2b8a0 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61  th individual va
2b8b0 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74  lues, not with t
2b8c0 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a  he containers.**
2b8d0 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68   used to hold th
2b8e0 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63  ose values..*/.c
2b8f0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2b900 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
2b910 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
2b920 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
2b930 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2b940 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c  n_decltype16(sql
2b950 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2b960 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b970 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51  : Evaluate An SQ
2b980 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  L Statement.**.*
2b990 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61  * After a [prepa
2b9a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68  red statement] h
2b9b0 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64  as been prepared
2b9c0 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a   using either.**
2b9d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2b9e0 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
2b9f0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2ba00 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  ()] or one of th
2ba10 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
2ba20 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
2ba30 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73  prepare()] or [s
2ba40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2ba50 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69  ()], this functi
2ba60 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61  on.** must be ca
2ba70 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  lled one or more
2ba80 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61   times to evalua
2ba90 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
2baa0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61  ..**.** The deta
2bab0 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76  ils of the behav
2bac0 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ior of the sqlit
2bad0 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66  e3_step() interf
2bae0 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  ace depend.** on
2baf0 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61   whether the sta
2bb00 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61  tement was prepa
2bb10 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65  red using the ne
2bb20 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61  wer "v2" interfa
2bb30 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ce.** [sqlite3_p
2bb40 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
2bb50 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2bb60 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65  e16_v2()] or the
2bb70 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a   older legacy.**
2bb80 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69   interface [sqli
2bb90 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
2bba0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
2bbb0 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75  are16()].  The u
2bbc0 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77  se of the.** new
2bbd0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
2bbe0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
2bbf0 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  or new applicati
2bc00 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61  ons but the lega
2bc10 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
2bc20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f  will continue to
2bc30 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a   be supported..*
2bc40 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67  *.** ^In the leg
2bc50 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
2bc60 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
2bc70 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b  will be either [
2bc80 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a  SQLITE_BUSY],.**
2bc90 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20   [SQLITE_DONE], 
2bca0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53  [SQLITE_ROW], [S
2bcb0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72  QLITE_ERROR], or
2bcc0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2bcd0 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22  ..** ^With the "
2bce0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61  v2" interface, a
2bcf0 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20  ny of the other 
2bd00 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f  [result codes] o
2bd10 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  r.** [extended r
2bd20 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67  esult codes] mig
2bd30 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  ht be returned a
2bd40 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  s well..**.** ^[
2bd50 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61  SQLITE_BUSY] mea
2bd60 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61  ns that the data
2bd70 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20  base engine was 
2bd80 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72  unable to acquir
2bd90 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  e the.** databas
2bda0 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73  e locks it needs
2bdb0 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20   to do its job. 
2bdc0 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65   ^If the stateme
2bdd0 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d  nt is a [COMMIT]
2bde0 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75  .** or occurs ou
2bdf0 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c  tside of an expl
2be00 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
2be10 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72  , then you can r
2be20 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74  etry the.** stat
2be30 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73  ement.  If the s
2be40 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20  tatement is not 
2be50 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f  a [COMMIT] and o
2be60 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a  ccurs within an.
2be70 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  ** explicit tran
2be80 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75  saction then you
2be90 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b   should rollback
2bea0 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
2beb0 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69   before.** conti
2bec0 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53  nuing..**.** ^[S
2bed0 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e  QLITE_DONE] mean
2bee0 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65  s that the state
2bef0 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65  ment has finishe
2bf00 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73  d executing.** s
2bf10 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71  uccessfully.  sq
2bf20 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
2bf30 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
2bf40 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20  d again on this 
2bf50 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
2bf60 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74  ne without first
2bf70 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2bf80 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65  3_reset()] to re
2bf90 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a  set the virtual.
2bfa0 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20  ** machine back 
2bfb0 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
2bfc0 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  tate..**.** ^If 
2bfd0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
2bfe0 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64  t being executed
2bff0 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74   returns any dat
2c000 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  a, then [SQLITE_
2c010 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  ROW].** is retur
2c020 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20  ned each time a 
2c030 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20  new row of data 
2c040 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f  is ready for pro
2c050 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a  cessing by the.*
2c060 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61  * caller. The va
2c070 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65  lues may be acce
2c080 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ssed using the [
2c090 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
2c0a0 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c  nctions]..** sql
2c0b0 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63  ite3_step() is c
2c0c0 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72  alled again to r
2c0d0 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74  etrieve the next
2c0e0 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a   row of data..**
2c0f0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52  .** ^[SQLITE_ERR
2c100 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61  OR] means that a
2c110 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20   run-time error 
2c120 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74  (such as a const
2c130 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69  raint.** violati
2c140 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64  on) has occurred
2c150 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
2c160 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
2c170 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a  called again on.
2c180 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20  ** the VM. More 
2c190 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20  information may 
2c1a0 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c  be found by call
2c1b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  ing [sqlite3_err
2c1c0 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68  msg()]..** ^With
2c1d0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
2c1e0 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70  rface, a more sp
2c1f0 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
2c200 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  e (for example,.
2c210 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  ** [SQLITE_INTER
2c220 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53  RUPT], [SQLITE_S
2c230 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f  CHEMA], [SQLITE_
2c240 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f  CORRUPT], and so
2c250 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62   forth).** can b
2c260 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61  e obtained by ca
2c270 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
2c280 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a  eset()] on the.*
2c290 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2c2a0 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65  ement].  ^In the
2c2b0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
2c2c0 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65  .** the more spe
2c2d0 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
2c2e0 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72   is returned dir
2c2f0 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33  ectly by sqlite3
2c300 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b  _step()..**.** [
2c310 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d  SQLITE_MISUSE] m
2c320 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68  eans that the th
2c330 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63  is routine was c
2c340 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69  alled inappropri
2c350 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70  ately..** Perhap
2c360 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20  s it was called 
2c370 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
2c380 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
2c390 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65  as.** already be
2c3a0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  en [sqlite3_fina
2c3b0 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64  lize | finalized
2c3c0 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74  ] or on one that
2c3d0 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73   had.** previous
2c3e0 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  ly returned [SQL
2c3f0 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53  ITE_ERROR] or [S
2c400 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72  QLITE_DONE].  Or
2c410 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20   it could.** be 
2c420 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
2c430 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
2c440 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65  connection is be
2c450 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20  ing used by two 
2c460 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61  or.** more threa
2c470 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d  ds at the same m
2c480 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a  oment in time..*
2c490 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72  *.** For all ver
2c4a0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
2c4b0 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64  up to and includ
2c4c0 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20  ing 3.6.23.1, a 
2c4d0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2c4e0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73  te3_reset()] was
2c4f0 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20   required after 
2c500 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72  sqlite3_step() r
2c510 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67  eturned anything
2c520 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  .** other than [
2c530 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f  SQLITE_ROW] befo
2c540 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  re any subsequen
2c550 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a  t invocation of.
2c560 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
2c570 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72  ).  Failure to r
2c580 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
2c590 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  d statement usin
2c5a0 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  g .** [sqlite3_r
2c5b0 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65  eset()] would re
2c5c0 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49  sult in an [SQLI
2c5d0 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72  TE_MISUSE] retur
2c5e0 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  n from.** sqlite
2c5f0 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61  3_step().  But a
2c600 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36  fter version 3.6
2c610 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73  .23.1, sqlite3_s
2c620 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63  tep() began.** c
2c630 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2c640 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74  reset()] automat
2c650 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63  ically in this c
2c660 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68  ircumstance rath
2c670 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72  er.** than retur
2c680 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53  ning [SQLITE_MIS
2c690 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e  USE].  This is n
2c6a0 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20  ot considered a 
2c6b0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a  compatibility.**
2c6c0 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61   break because a
2c6d0 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ny application t
2c6e0 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65  hat ever receive
2c6f0 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  s an SQLITE_MISU
2c700 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62  SE error.** is b
2c710 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74  roken by definit
2c720 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ion.  The [SQLIT
2c730 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54  E_OMIT_AUTORESET
2c740 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
2c750 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20  ption.** can be 
2c760 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20  used to restore 
2c770 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  the legacy behav
2c780 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f  ior..**.** <b>Go
2c790 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c  ofy Interface Al
2c7a0 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20  ert:</b> In the 
2c7b0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
2c7c0 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  , the sqlite3_st
2c7d0 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61  ep().** API alwa
2c7e0 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e  ys returns a gen
2c7f0 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c  eric error code,
2c800 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
2c810 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a   following any.*
2c820 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68  * error other th
2c830 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  an [SQLITE_BUSY]
2c840 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53   and [SQLITE_MIS
2c850 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20  USE].  You must 
2c860 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
2c870 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
2c880 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2c890 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  ] in order to fi
2c8a0 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  nd one of the.**
2c8b0 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
2c8c0 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74   codes] that bet
2c8d0 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68  ter describes th
2c8e0 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61  e error..** We a
2c8f0 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69  dmit that this i
2c900 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e  s a goofy design
2c910 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68  .  The problem h
2c920 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a  as been fixed.**
2c930 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69   with the "v2" i
2c940 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f  nterface.  If yo
2c950 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66  u prepare all of
2c960 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d   your SQL statem
2c970 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69  ents.** using ei
2c980 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
2c990 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
2c9a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2c9b0 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a  6_v2()] instead.
2c9c0 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ** of the legacy
2c9d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2c9e0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
2c9f0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69  3_prepare16()] i
2ca00 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68  nterfaces,.** th
2ca10 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  en the more spec
2ca20 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
2ca30 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20  s] are returned 
2ca40 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73  directly.** by s
2ca50 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
2ca60 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22  The use of the "
2ca70 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
2ca80 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f   recommended..*/
2ca90 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65  .int sqlite3_ste
2caa0 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  p(sqlite3_stmt*)
2cab0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2cac0 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  F: Number of col
2cad0 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74  umns in a result
2cae0 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20   set.**.** ^The 
2caf0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2cb00 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20  nt(P) interface 
2cb10 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2cb20 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2cb30 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
2cb40 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
2cb50 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72  t set of [prepar
2cb60 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
2cb70 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64  .** ^If prepared
2cb80 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65   statement P doe
2cb90 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c  s not have resul
2cba0 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75  ts ready to retu
2cbb0 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73  rn.** (via calls
2cbc0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
2cbd0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71  _column_int | sq
2cbe0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29  lite3_column_*()
2cbf0 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  ] of.** interfac
2cc00 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  es) then sqlite3
2cc10 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
2cc20 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68  eturns 0..** ^Th
2cc30 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2cc40 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20  ount(P) routine 
2cc50 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69  also returns 0 i
2cc60 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f P is a NULL po
2cc70 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73  inter..** ^The s
2cc80 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2cc90 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74  t(P) routine ret
2cca0 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72  urns 0 if the pr
2ccb0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a  evious call to.*
2ccc0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d  * [sqlite3_step]
2ccd0 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51  (P) returned [SQ
2cce0 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68  LITE_DONE].  ^Th
2ccf0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2cd00 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20  ount(P).** will 
2cd10 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20  return non-zero 
2cd20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  if previous call
2cd30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2cd40 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a  p](P) returned.*
2cd50 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  * [SQLITE_ROW], 
2cd60 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61  except in the ca
2cd70 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d  se of the [PRAGM
2cd80 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61  A incremental_va
2cd90 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69  cuum].** where i
2cda0 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  t always returns
2cdb0 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68   zero since each
2cdc0 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75   step of that mu
2cdd0 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67  lti-step.** prag
2cde0 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c  ma returns 0 col
2cdf0 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a  umns of data..**
2ce00 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2ce10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
2ce20 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71  unt()].*/.int sq
2ce30 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2ce40 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2ce50 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2ce60 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e  PI3REF: Fundamen
2ce70 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a  tal Datatypes.**
2ce80 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54   KEYWORDS: SQLIT
2ce90 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45  E_TEXT.**.** ^(E
2cea0 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51  very value in SQ
2ceb0 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20  Lite has one of 
2cec0 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c  five fundamental
2ced0 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a   datatypes:.**.*
2cee0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36  * <ul>.** <li> 6
2cef0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
2cf00 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  eger.** <li> 64-
2cf10 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e  bit IEEE floatin
2cf20 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a  g point number.*
2cf30 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a  * <li> string.**
2cf40 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c   <li> BLOB.** <l
2cf50 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e  i> NULL.** </ul>
2cf60 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  )^.**.** These c
2cf70 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64  onstants are cod
2cf80 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74  es for each of t
2cf90 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a  hose types..**.*
2cfa0 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
2cfb0 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73  SQLITE_TEXT cons
2cfc0 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73  tant was also us
2cfd0 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72  ed in SQLite ver
2cfe0 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20  sion 2.** for a 
2cff0 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65  completely diffe
2d000 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53  rent meaning.  S
2d010 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e  oftware that lin
2d020 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a  ks against both.
2d030 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
2d040 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76  n 2 and SQLite v
2d050 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20  ersion 3 should 
2d060 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  use SQLITE3_TEXT
2d070 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f  , not.** SQLITE_
2d080 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  TEXT..*/.#define
2d090 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20   SQLITE_INTEGER 
2d0a0 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
2d0b0 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65  E_FLOAT    2.#de
2d0c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42  fine SQLITE_BLOB
2d0d0 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
2d0e0 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35  QLITE_NULL     5
2d0f0 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54  .#ifdef SQLITE_T
2d100 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  EXT.# undef SQLI
2d110 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20  TE_TEXT.#else.# 
2d120 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
2d130 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a  XT     3.#endif.
2d140 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f  #define SQLITE3_
2d150 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a  TEXT     3../*.*
2d160 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
2d170 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41  lt Values From A
2d180 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52   Query.** KEYWOR
2d190 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65  DS: {column acce
2d1a0 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  ss functions}.**
2d1b0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2d1c0 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73  es form the "res
2d1d0 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66 61  ult set" interfa
2d1e0 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ce..**.** ^These
2d1f0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2d200 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
2d210 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75  ut a single colu
2d220 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  mn of the curren
2d230 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  t.** result row 
2d240 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e  of a query.  ^In
2d250 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20   every case the 
2d260 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
2d270 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
2d280 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  o the [prepared 
2d290 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
2d2a0 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74  is being evaluat
2d2b0 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
2d2c0 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20  _stmt*].** that 
2d2d0 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f  was returned fro
2d2e0 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  m [sqlite3_prepa
2d2f0 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  re_v2()] or one 
2d300 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  of its variants)
2d310 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f  .** and the seco
2d320 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
2d330 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
2d340 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68  column for which
2d350 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
2d360 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
2d370 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  ed. ^The leftmos
2d380 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
2d390 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74  result set has t
2d3a0 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e  he index 0..** ^
2d3b0 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  The number of co
2d3c0 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
2d3d0 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72  ult can be deter
2d3e0 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  mined using.** [
2d3f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
2d400 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  ount()]..**.** I
2d410 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
2d420 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72  ent does not cur
2d430 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20  rently point to 
2d440 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20  a valid row, or 
2d450 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  if the.** column
2d460 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
2d470 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75   range, the resu
2d480 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  lt is undefined.
2d490 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2d4a0 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63  es may only be c
2d4b0 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d  alled when the m
2d4c0 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
2d4d0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
2d4e0 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
2d4f0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
2d500 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20   and neither.** 
2d510 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2d520 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  ] nor [sqlite3_f
2d530 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20  inalize()] have 
2d540 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73  been called subs
2d550 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20  equently..** If 
2d560 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
2d570 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
2d580 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
2d590 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
2d5a0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2d5b0 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71  ()] or after [sq
2d5c0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
2d5d0 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f  s returned.** so
2d5e0 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
2d5f0 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  an [SQLITE_ROW],
2d600 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2d610 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49   undefined..** I
2d620 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
2d630 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
2d640 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
2d650 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a  te3_finalize()].
2d660 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  ** are called fr
2d670 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74  om a different t
2d680 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20  hread while any 
2d690 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2d6a0 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67  s.** are pending
2d6b0 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  , then the resul
2d6c0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
2d6d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2d6e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2d6f0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
2d700 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ns the.** [SQLIT
2d710 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
2d720 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74  type code] for t
2d730 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20  he initial data 
2d740 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72  type.** of the r
2d750 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e  esult column.  ^
2d760 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c  The returned val
2d770 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  ue is one of [SQ
2d780 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a  LITE_INTEGER],.*
2d790 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  * [SQLITE_FLOAT]
2d7a0 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c  , [SQLITE_TEXT],
2d7b0 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20   [SQLITE_BLOB], 
2d7c0 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  or [SQLITE_NULL]
2d7d0 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20  .  The value.** 
2d7e0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2d7f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2d800 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e  ) is only meanin
2d810 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a  gful if no type.
2d820 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68  ** conversions h
2d830 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20  ave occurred as 
2d840 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e  described below.
2d850 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63    After a type c
2d860 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68  onversion,.** th
2d870 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
2d880 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2d890 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64  mn_type() is und
2d8a0 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a  efined.  Future.
2d8b0 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ** versions of S
2d8c0 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65  QLite may change
2d8d0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
2d8e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d8f0 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77  type().** follow
2d900 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ing a type conve
2d910 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rsion..**.** ^If
2d920 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2d930 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73   BLOB or UTF-8 s
2d940 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
2d950 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2d960 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  tes().** routine
2d970 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2d980 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2d990 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
2d9a0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2d9b0 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
2d9c0 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  16 string, then 
2d9d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2d9e0 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a  ytes() converts.
2d9f0 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
2da00 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20   UTF-8 and then 
2da10 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2da20 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
2da30 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2da40 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
2da50 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
2da60 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73  olumn_bytes() us
2da70 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
2da80 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
2da90 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
2daa0 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69   to a UTF-8 stri
2dab0 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
2dac0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
2dad0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
2dae0 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
2daf0 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c   result is NULL,
2db00 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2db10 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74  lumn_bytes() ret
2db20 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
2db30 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2db40 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
2db50 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20  -16 string then 
2db60 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
2db70 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20  mn_bytes16().** 
2db80 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2db90 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2dba0 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
2dbb0 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
2dbc0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2dbd0 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c   a UTF-8 string,
2dbe0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2dbf0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63  lumn_bytes16() c
2dc00 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
2dc10 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20  tring to UTF-16 
2dc20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
2dc30 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2dc40 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
2dc50 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
2dc60 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
2dc70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2dc80 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a  ytes16() uses.**
2dc90 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
2dca0 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
2dcb0 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
2dcc0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61   UTF-16 string a
2dcd0 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
2dce0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2dcf0 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
2dd00 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2dd10 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ult is NULL, the
2dd20 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2dd30 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72  _bytes16() retur
2dd40 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
2dd50 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
2dd60 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
2dd70 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
2dd80 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
2dd90 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2dda0 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64  )] do not includ
2ddb0 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  e the zero termi
2ddc0 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e  nators at the en
2ddd0 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69  d.** of the stri
2dde0 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74  ng.  ^For clarit
2ddf0 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65  y: the values re
2de00 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
2de10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2de20 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  es()] and [sqlit
2de30 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2de40 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d  6()] are the num
2de50 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20  ber of.** bytes 
2de60 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e  in the string, n
2de70 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
2de80 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
2de90 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75  ** ^Strings retu
2dea0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
2deb0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e  column_text() an
2dec0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2ded0 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76  _text16(),.** ev
2dee0 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73  en empty strings
2def0 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72  , are always zer
2df00 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
2df10 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  The return.** va
2df20 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
2df30 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
2df40 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  or a zero-length
2df50 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20   BLOB is a NULL 
2df60 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
2df70 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  The object retur
2df80 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
2df90 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
2dfa0 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  is an.** [unprot
2dfb0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2dfc0 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e  lue] object.  An
2dfd0 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
2dfe0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2dff0 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  t.** may only be
2e000 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69   used with [sqli
2e010 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
2e020 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
2e030 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a  esult_value()]..
2e040 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f  ** If the [unpro
2e050 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2e060 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74  alue] object ret
2e070 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
2e080 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2e090 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20  e()] is used in 
2e0a0 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69  any other way, i
2e0b0 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a  ncluding calls.*
2e0c0 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  * to routines li
2e0d0 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ke [sqlite3_valu
2e0e0 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74  e_int()], [sqlit
2e0f0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
2e100 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
2e110 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
2e120 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
2e130 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
2e140 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2e150 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f  tines attempt to
2e160 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
2e170 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72  ue where appropr
2e180 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65  iate.  ^For.** e
2e190 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69  xample, if the i
2e1a0 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
2e1b0 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20  tation is FLOAT 
2e1c0 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c  and a text resul
2e1d0 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65  t.** is requeste
2e1e0 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  d, [sqlite3_snpr
2e1f0 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20  intf()] is used 
2e200 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65  internally to pe
2e210 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e  rform the.** con
2e220 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69  version automati
2e230 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f  cally.  ^(The fo
2e240 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65  llowing table de
2e250 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72  tails the conver
2e260 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72  sions.** that ar
2e270 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a  e applied:.**.**
2e280 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a   <blockquote>.**
2e290 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
2e2a0 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  1">.** <tr><th> 
2e2b0 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65  Internal<br>Type
2e2c0 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c   <th> Requested<
2e2d0 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f  br>Type <th>  Co
2e2e0 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c  nversion.**.** <
2e2f0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
2e300 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
2e310 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
2e320 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2e330 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  LL    <td>  FLOA
2e340 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
2e350 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c   is 0.0.** <tr><
2e360 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
2e370 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2e380 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c   Result is a NUL
2e390 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
2e3a0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
2e3b0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
2e3c0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e  d> Result is a N
2e3d0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
2e3e0 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
2e3f0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
2e400 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
2e410 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f  m integer to flo
2e420 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  at.** <tr><td> I
2e430 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54  NTEGER  <td>   T
2e440 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
2e450 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
2e460 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74  he integer.** <t
2e470 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
2e480 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2e490 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45  td> Same as INTE
2e4a0 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  GER->TEXT.** <tr
2e4b0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
2e4c0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
2e4d0 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54  d> [CAST] to INT
2e4e0 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  EGER.** <tr><td>
2e4f0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
2e500 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
2e510 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
2e520 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74   the float.** <t
2e530 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
2e540 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2e550 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c  td> [CAST] to BL
2e560 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  OB.** <tr><td>  
2e570 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54  TEXT    <td> INT
2e580 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53  EGER   <td> [CAS
2e590 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a  T] to INTEGER.**
2e5a0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
2e5b0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
2e5c0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
2e5d0 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64   REAL.** <tr><td
2e5e0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
2e5f0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e    BLOB    <td> N
2e600 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e  o change.** <tr>
2e610 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
2e620 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
2e630 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45  > [CAST] to INTE
2e640 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  GER.** <tr><td> 
2e650 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46   BLOB    <td>  F
2e660 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41  LOAT    <td> [CA
2e670 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c  ST] to REAL.** <
2e680 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
2e690 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2e6a0 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
2e6b0 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
2e6c0 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
2e6d0 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
2e6e0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  >)^.**.** The ta
2e6f0 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20  ble above makes 
2e700 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61  reference to sta
2e710 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20  ndard C library 
2e720 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29  functions atoi()
2e730 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20  .** and atof(). 
2e740 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74   SQLite does not
2e750 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73   really use thes
2e760 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74  e functions.  It
2e770 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20   has its.** own 
2e780 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72  equivalent inter
2e790 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54  nal routines.  T
2e7a0 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74  he atoi() and at
2e7b0 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a  of() names are.*
2e7c0 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61  * used in the ta
2e7d0 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20  ble for brevity 
2e7e0 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79  and because they
2e7f0 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f   are familiar to
2e800 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72   most.** C progr
2e810 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  ammers..**.** No
2e820 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70  te that when typ
2e830 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63  e conversions oc
2e840 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65  cur, pointers re
2e850 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a  turned by prior.
2e860 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
2e870 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2e880 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
2e890 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72  n_text(), and/or
2e8a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2e8b0 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20  mn_text16() may 
2e8c0 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  be invalidated..
2e8d0 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69  ** Type conversi
2e8e0 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20  ons and pointer 
2e8f0 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69  invalidations mi
2e900 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ght occur.** in 
2e910 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
2e920 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ses:.**.** <ul>.
2e930 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
2e940 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61  ial content is a
2e950 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65   BLOB and sqlite
2e960 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2e970 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
2e980 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2e990 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41  () is called.  A
2e9a0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
2e9b0 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e   might.**      n
2e9c0 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20  eed to be added 
2e9d0 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f  to the string.</
2e9e0 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
2e9f0 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
2ea00 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e  is UTF-8 text an
2ea10 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2ea20 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a  _bytes16() or.**
2ea30 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
2ea40 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
2ea50 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
2ea60 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
2ea70 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
2ea80 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a  to UTF-16.</li>.
2ea90 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
2eaa0 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
2eab0 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73  TF-16 text and s
2eac0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2ead0 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  tes() or.**     
2eae0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2eaf0 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64  text() is called
2eb00 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
2eb10 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
2eb20 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
2eb30 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  8.</li>.** </ul>
2eb40 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69  .**.** ^Conversi
2eb50 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d  ons between UTF-
2eb60 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c  16be and UTF-16l
2eb70 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e  e are always don
2eb80 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64  e in place and d
2eb90 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64  o.** not invalid
2eba0 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e  ate a prior poin
2ebb0 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  ter, though of c
2ebc0 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e  ourse the conten
2ebd0 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a  t of the buffer.
2ebe0 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f  ** that the prio
2ebf0 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65  r pointer refere
2ec00 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62  nces will have b
2ec10 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f  een modified.  O
2ec20 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66  ther kinds.** of
2ec30 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20   conversion are 
2ec40 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68  done in place wh
2ec50 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c  en it is possibl
2ec60 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73  e, but sometimes
2ec70 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74   they.** are not
2ec80 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e   possible and in
2ec90 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69   those cases pri
2eca0 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20  or pointers are 
2ecb0 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a  invalidated..**.
2ecc0 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e  ** The safest an
2ecd0 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d  d easiest to rem
2ece0 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20  ember policy is 
2ecf0 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20  to invoke these 
2ed00 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f  routines.** in o
2ed10 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
2ed20 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ing ways:.**.** 
2ed30 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  <ul>.**  <li>sql
2ed40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2ed50 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
2ed60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2ed70 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
2ed80 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
2ed90 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65  n_blob() followe
2eda0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2edb0 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
2edc0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
2edd0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2ede0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
2edf0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2ee00 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  s16()</li>.** </
2ee10 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  ul>.**.** In oth
2ee20 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68  er words, you sh
2ee30 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65  ould call sqlite
2ee40 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
2ee50 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2ee60 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71  mn_blob(), or sq
2ee70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2ee80 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66  t16() first to f
2ee90 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a  orce the result.
2eea0 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  ** into the desi
2eeb0 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e  red format, then
2eec0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
2eed0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
2eee0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
2eef0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
2ef00 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f   find the size o
2ef10 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44  f the result.  D
2ef20 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a  o not mix calls.
2ef30 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
2ef40 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73  lumn_text() or s
2ef50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2ef60 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20  ob() with calls 
2ef70 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
2ef80 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20  lumn_bytes16(), 
2ef90 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63  and do not mix c
2efa0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2efb0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a  column_text16().
2efc0 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  ** with calls to
2efd0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2efe0 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  bytes()..**.** ^
2eff0 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  The pointers ret
2f000 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20  urned are valid 
2f010 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e  until a type con
2f020 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61  version occurs a
2f030 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61  s.** described a
2f040 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b  bove, or until [
2f050 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2f060 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
2f070 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
2f080 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2f090 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65  is called.  ^The
2f0a0 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73   memory space us
2f0b0 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e  ed to hold strin
2f0c0 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20  gs.** and BLOBs 
2f0d0 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74  is freed automat
2f0e0 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e  ically.  Do <b>n
2f0f0 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20  ot</b> pass the 
2f100 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
2f110 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
2f120 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2f130 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ], [sqlite3_colu
2f140 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e  mn_text()], etc.
2f150 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65   into.** [sqlite
2f160 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_free()]..**.**
2f170 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61   ^(If a memory a
2f180 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
2f190 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
2f1a0 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  e evaluation of 
2f1b0 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20  any.** of these 
2f1c0 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61  routines, a defa
2f1d0 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74  ult value is ret
2f1e0 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61  urned.  The defa
2f1f0 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  ult value.** is 
2f200 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67  either the integ
2f210 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69  er 0, the floati
2f220 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20  ng point number 
2f230 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a  0.0, or a NULL.*
2f240 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73  * pointer.  Subs
2f250 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
2f260 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
2f270 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  ()] will return.
2f280 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
2f290 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  ].)^.*/.const vo
2f2a0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2f2b0 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  mn_blob(sqlite3_
2f2c0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2f2d0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
2f2e0 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74  lumn_bytes(sqlit
2f2f0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2f300 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
2f310 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2f320 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2f330 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65  nt iCol);.double
2f340 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f350 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
2f360 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2f370 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2f380 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  umn_int(sqlite3_
2f390 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2f3a0 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
2f3b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
2f3c0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
2f3d0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
2f3e0 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
2f3f0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2f400 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  mn_text(sqlite3_
2f410 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2f420 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2f430 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2f440 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
2f450 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
2f460 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2f470 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  _type(sqlite3_st
2f480 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2f490 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73  sqlite3_value *s
2f4a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
2f4b0 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
2f4c0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f  *, int iCol);../
2f4d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2f4e0 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65  estroy A Prepare
2f4f0 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
2f500 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ct.**.** ^The sq
2f510 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2f520 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
2f530 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20  led to delete a 
2f540 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2f550 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ent]..** ^If the
2f560 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61   most recent eva
2f570 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  luation of the s
2f580 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74  tatement encount
2f590 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a  ered no errors.*
2f5a0 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74  * or if the stat
2f5b0 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62  ement is never b
2f5c0 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74  een evaluated, t
2f5d0 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  hen sqlite3_fina
2f5e0 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a  lize() returns.*
2f5f0 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49  * SQLITE_OK.  ^I
2f600 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2f610 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
2f620 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c  statement S fail
2f630 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  ed, then.** sqli
2f640 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20  te3_finalize(S) 
2f650 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72  returns the appr
2f660 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
2f670 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  ode] or.** [exte
2f680 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
2f690 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2f6a0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
2f6b0 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
2f6c0 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f  called at any po
2f6d0 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68  int during.** th
2f6e0 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20  e life cycle of 
2f6f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2f700 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72  ent] S:.** befor
2f710 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73  e statement S is
2f720 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c   ever evaluated,
2f730 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72   after.** one or
2f740 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b   more calls to [
2f750 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2f760 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63  , or after any c
2f770 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  all.** to [sqlit
2f780 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72  e3_step()] regar
2f790 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
2f7a0 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74   or not the stat
2f7b0 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d  ement has.** com
2f7c0 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e  pleted execution
2f7d0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e  ..**.** ^Invokin
2f7e0 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  g sqlite3_finali
2f7f0 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70  ze() on a NULL p
2f800 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d  ointer is a harm
2f810 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a  less no-op..**.*
2f820 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
2f830 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20  n must finalize 
2f840 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20  every [prepared 
2f850 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72  statement] in or
2f860 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  der to avoid.** 
2f870 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20  resource leaks. 
2f880 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75   It is a grievou
2f890 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20  s error for the 
2f8a0 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74  application to t
2f8b0 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70  ry to use.** a p
2f8c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f8d0 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  t after it has b
2f8e0 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20  een finalized.  
2f8f0 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65  Any use of a pre
2f900 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2f910 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
2f920 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63  been finalized c
2f930 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  an result in und
2f940 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e  efined and.** un
2f950 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69  desirable behavi
2f960 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61  or such as segfa
2f970 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f  ults and heap co
2f980 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74  rruption..*/.int
2f990 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2f9a0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  e(sqlite3_stmt *
2f9b0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2f9c0 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
2f9d0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2f9e0 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ent Object.**.**
2f9f0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2fa00 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  et() function is
2fa10 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74   called to reset
2fa20 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2fa30 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
2fa40 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  t back to its in
2fa50 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61  itial state, rea
2fa60 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63  dy to be re-exec
2fa70 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51  uted..** ^Any SQ
2fa80 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69  L statement vari
2fa90 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76  ables that had v
2faa0 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74  alues bound to t
2fab0 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  hem using.** the
2fac0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2fad0 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
2fae0 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61  nd_*() API] reta
2faf0 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e  in their values.
2fb00 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33  .** Use [sqlite3
2fb10 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
2fb20 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
2fb30 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20  bindings..**.** 
2fb40 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
2fb50 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
2fb60 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72  e resets the [pr
2fb70 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2fb80 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74  ] S.** back to t
2fb90 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
2fba0 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a  its program..**.
2fbb0 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
2fbc0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
2fbd0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2fbe0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
2fbf0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2fc00 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c   S returned [SQL
2fc10 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c  ITE_ROW] or [SQL
2fc20 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72  ITE_DONE],.** or
2fc30 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   if [sqlite3_ste
2fc40 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20  p(S)] has never 
2fc50 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c  before been call
2fc60 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e  ed on S,.** then
2fc70 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2fc80 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  S)] returns [SQL
2fc90 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
2fca0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
2fcb0 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
2fcc0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
2fcd0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2fce0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
2fcf0 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f  ndicated an erro
2fd00 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69  r, then.** [sqli
2fd10 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
2fd20 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72  turns an appropr
2fd30 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
2fd40 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  ]..**.** ^The [s
2fd50 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2fd60 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20   interface does 
2fd70 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
2fd80 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20  alues.** of any 
2fd90 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2fda0 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20  ob|bindings] on 
2fdb0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2fdc0 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69  atement] S..*/.i
2fdd0 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  nt sqlite3_reset
2fde0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2fdf0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2fe00 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f  PI3REF: Create O
2fe10 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46  r Redefine SQL F
2fe20 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57  unctions.** KEYW
2fe30 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20  ORDS: {function 
2fe40 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
2fe50 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
2fe60 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
2fe70 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2fe80 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  n}.** KEYWORDS: 
2fe90 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
2fea0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2feb0 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ns}.**.** ^These
2fec0 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c   functions (coll
2fed0 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61  ectively known a
2fee0 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  s "function crea
2fef0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a  tion routines").
2ff00 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ** are used to a
2ff10 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  dd SQL functions
2ff20 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f   or aggregates o
2ff30 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68  r to redefine th
2ff40 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66  e behavior.** of
2ff50 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75   existing SQL fu
2ff60 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
2ff70 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79  gates.  The only
2ff80 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74   differences bet
2ff90 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f  ween.** these ro
2ffa0 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74  utines are the t
2ffb0 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70  ext encoding exp
2ffc0 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65  ected for.** the
2ffd0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2ffe0 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  r (the name of t
2fff0 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e  he function bein
30000 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e  g created).** an
30010 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f  d the presence o
30020 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64  r absence of a d
30030 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61  estructor callba
30040 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70  ck for.** the ap
30050 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
30060 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
30070 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
30080 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62  er is the [datab
30090 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
300a0 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c  to which the SQL
300b0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
300c0 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49  to be added.  ^I
300d0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
300e0 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20   uses more than 
300f0 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  one database.** 
30100 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20  connection then 
30110 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
30120 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
30130 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a  s must be added.
30140 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ** to each datab
30150 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
30160 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
30170 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
30180 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
30190 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  me of the SQL fu
301a0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65  nction to be cre
301b0 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66  ated or.** redef
301c0 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67  ined.  ^The leng
301d0 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69  th of the name i
301e0 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35  s limited to 255
301f0 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d   bytes in a UTF-
30200 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74  8.** representat
30210 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f  ion, exclusive o
30220 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  f the zero-termi
30230 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68  nator.  ^Note th
30240 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c  at the name.** l
30250 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69  ength limit is i
30260 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e  n UTF-8 bytes, n
30270 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f  ot characters no
30280 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20  r UTF-16 bytes. 
30290 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70   .** ^Any attemp
302a0 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75  t to create a fu
302b0 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f  nction with a lo
302c0 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c  nger name.** wil
302d0 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c  l result in [SQL
302e0 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e  ITE_MISUSE] bein
302f0 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  g returned..**.*
30300 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72  * ^The third par
30310 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a  ameter (nArg).**
30320 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
30330 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  f arguments that
30340 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
30350 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
30360 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69  e takes. ^If thi
30370 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d  s parameter is -
30380 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
30390 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
303a0 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b  ggregate may tak
303b0 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20  e any number of 
303c0 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65  arguments betwee
303d0 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69  n 0 and the limi
303e0 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c  t.** set by [sql
303f0 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c  ite3_limit]([SQL
30400 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
30410 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68  ON_ARG]).  If th
30420 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
30430 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61  eter is less tha
30440 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20  n -1 or greater 
30450 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68  than 127 then th
30460 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a  e behavior is.**
30470 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
30480 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
30490 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65  rameter, eTextRe
304a0 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61  p, specifies wha
304b0 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  t.** [SQLITE_UTF
304c0 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  8 | text encodin
304d0 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63  g] this SQL func
304e0 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72  tion prefers for
304f0 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65  .** its paramete
30500 72 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  rs.  The applica
30510 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20  tion should set 
30520 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 74  this parameter t
30530 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  o.** [SQLITE_UTF
30540 31 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e  16LE] if the fun
30550 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
30560 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a  tion invokes .**
30570 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
30580 74 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61  text16le()] on a
30590 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c  n input, or [SQL
305a0 49 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20  ITE_UTF16BE] if 
305b0 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
305c0 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73  ation invokes [s
305d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
305e0 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69  t16be()] on an i
305f0 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c  nput, or.** [SQL
30600 49 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73  ITE_UTF16] if [s
30610 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
30620 74 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  t16()] is used, 
30630 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  or [SQLITE_UTF8]
30640 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20  .** otherwise.  
30650 5e 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75  ^The same SQL fu
30660 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65  nction may be re
30670 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c  gistered multipl
30680 65 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a  e times using.**
30690 20 64 69 66 66 65 72 65 6e 74 20 70 72 65 66 65   different prefe
306a0 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
306b0 6e 67 73 2c 20 77 69 74 68 20 64 69 66 66 65 72  ngs, with differ
306c0 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
306d0 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ons for.** each 
306e0 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68  encoding..** ^Wh
306f0 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  en multiple impl
30700 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
30710 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
30720 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20   are available, 
30730 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70  SQLite.** will p
30740 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74  ick the one that
30750 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65   involves the le
30760 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
30770 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  ta conversion..*
30780 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
30790 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f   parameter may o
307a0 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65  ptionally be ORe
307b0 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44  d with [SQLITE_D
307c0 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a  ETERMINISTIC].**
307d0 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20   to signal that 
307e0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  the function wil
307f0 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  l always return 
30800 74 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20  the same result 
30810 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d  given.** the sam
30820 65 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20  e inputs within 
30830 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
30840 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51  tement.  Most SQ
30850 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a  L functions are.
30860 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63  ** deterministic
30870 2e 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20  .  The built-in 
30880 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66  [random()] SQL f
30890 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78  unction is an ex
308a0 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75  ample of a.** fu
308b0 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e  nction that is n
308c0 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63  ot deterministic
308d0 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 71 75  .  The SQLite qu
308e0 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61  ery planner is a
308f0 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72  ble to.** perfor
30900 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74  m additional opt
30910 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65  imizations on de
30920 74 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63  terministic func
30930 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a  tions, so use.**
30940 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
30950 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66  DETERMINISTIC] f
30960 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  lag is recommend
30970 65 64 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c  ed where possibl
30980 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  e..**.** ^(The f
30990 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  ifth parameter i
309a0 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70  s an arbitrary p
309b0 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70  ointer.  The imp
309c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
309d0 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63  he.** function c
309e0 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74  an gain access t
309f0 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75  o this pointer u
30a00 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73  sing [sqlite3_us
30a10 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a  er_data()].)^.**
30a20 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20  .** ^The sixth, 
30a30 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68  seventh and eigh
30a40 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78  th parameters, x
30a50 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20  Func, xStep and 
30a60 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70  xFinal, are.** p
30a70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e  ointers to C-lan
30a80 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20  guage functions 
30a90 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
30aa0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
30ab0 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e  or.** aggregate.
30ac0 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66   ^A scalar SQL f
30ad0 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
30ae0 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
30af0 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a  on of the xFunc.
30b00 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79  ** callback only
30b10 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  ; NULL pointers 
30b20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61  must be passed a
30b30 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20  s the xStep and 
30b40 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65  xFinal.** parame
30b50 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67  ters. ^An aggreg
30b60 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
30b70 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
30b80 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78  lementation of x
30b90 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e  Step.** and xFin
30ba0 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e  al and NULL poin
30bb0 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73  ter must be pass
30bc0 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54  ed for xFunc. ^T
30bd0 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73  o delete an exis
30be0 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63  ting.** SQL func
30bf0 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
30c00 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69  e, pass NULL poi
30c10 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68  nters for all th
30c20 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ree function.** 
30c30 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a  callbacks..**.**
30c40 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20   ^(If the ninth 
30c50 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
30c60 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
30c70 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  tion_v2() is not
30c80 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69   NULL,.** then i
30c90 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20  t is destructor 
30ca0 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
30cb0 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
30cc0 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75  . .** The destru
30cd0 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20  ctor is invoked 
30ce0 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f  when the functio
30cf0 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69  n is deleted, ei
30d00 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a  ther by being.**
30d10 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77   overloaded or w
30d20 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
30d30 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
30d40 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65  es.)^.** ^The de
30d50 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f  structor is also
30d60 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20   invoked if the 
30d70 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
30d80 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
30d90 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a  on_v2() fails..*
30da0 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74  * ^When the dest
30db0 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
30dc0 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72  of the tenth par
30dd0 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65  ameter is invoke
30de0 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73  d, it.** is pass
30df0 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  ed a single argu
30e00 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
30e10 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c  copy of the appl
30e20 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a  ication data .**
30e30 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77   pointer which w
30e40 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72  as the fifth par
30e50 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
30e60 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
30e70 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49  n_v2()..**.** ^I
30e80 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  t is permitted t
30e90 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69  o register multi
30ea0 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
30eb0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a  ons of the same.
30ec0 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74  ** functions wit
30ed0 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  h the same name 
30ee0 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20  but with either 
30ef0 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72  differing number
30f00 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  s of.** argument
30f10 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70  s or differing p
30f20 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
30f30 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74  codings.  ^SQLit
30f40 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68  e will use.** th
30f50 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
30f60 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65   that most close
30f70 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77  ly matches the w
30f80 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a  ay in which the.
30f90 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
30fa0 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e  is used.  ^A fun
30fb0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
30fc0 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d  tion with a non-
30fd0 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67  negative.** nArg
30fe0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
30ff0 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61  better match tha
31000 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  n a function imp
31010 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
31020 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e  .** a negative n
31030 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  Arg.  ^A functio
31040 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66  n where the pref
31050 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
31060 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74  ing.** matches t
31070 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f  he database enco
31080 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72  ding is a better
31090 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61  .** match than a
310a0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
310b0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  the encoding is 
310c0 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20  different.  .** 
310d0 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
310e0 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
310f0 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74  ifference is bet
31100 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64  ween UTF16le and
31110 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61   UTF16be.** is a
31120 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68   closer match th
31130 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
31140 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
31150 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a   difference is.*
31160 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61  * between UTF8 a
31170 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20  nd UTF16..**.** 
31180 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69  ^Built-in functi
31190 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c  ons may be overl
311a0 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70  oaded by new app
311b0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
311c0 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a   functions..**.*
311d0 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  * ^An applicatio
311e0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
311f0 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  on is permitted 
31200 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a  to call other.**
31210 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
31220 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75  es.  However, su
31230 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f  ch calls must no
31240 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64  t.** close the d
31250 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
31260 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20  on nor finalize 
31270 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65  or reset the pre
31280 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
31290 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20  nt in which the 
312a0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
312b0 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ing..*/.int sqli
312c0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
312d0 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
312e0 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
312f0 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
31300 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
31310 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
31320 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
31330 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
31340 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
31350 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
31360 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
31370 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
31380 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
31390 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
313a0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
313b0 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69  3_context*).);.i
313c0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
313d0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20  e_function16(.  
313e0 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
313f0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63  onst void *zFunc
31400 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
31410 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
31420 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
31430 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
31440 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
31450 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
31460 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
31470 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
31480 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
31490 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
314a0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
314b0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
314c0 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  xt*).);.int sqli
314d0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
314e0 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ion_v2(.  sqlite
314f0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
31500 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
31510 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
31520 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
31530 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
31540 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
31550 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
31560 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
31570 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
31580 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
31590 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
315a0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
315b0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
315c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a  ite3_context*),.
315d0 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
315e0 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a  )(void*).);../*.
315f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78  ** CAPI3REF: Tex
31600 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a  t Encodings.**.*
31610 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
31620 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20   define integer 
31630 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65  codes that repre
31640 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73  sent the various
31650 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  .** text encodin
31660 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  gs supported by 
31670 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69  SQLite..*/.#defi
31680 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20  ne SQLITE_UTF8  
31690 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
316a0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  ne SQLITE_UTF16L
316b0 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69  E        2.#defi
316c0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42  ne SQLITE_UTF16B
316d0 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  E        3.#defi
316e0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20  ne SQLITE_UTF16 
316f0 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a           4    /*
31700 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65   Use native byte
31710 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e   order */.#defin
31720 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20  e SQLITE_ANY    
31730 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20          5    /* 
31740 44 65 70 72 65 63 61 74 65 64 20 2a 2f 0a 23 64  Deprecated */.#d
31750 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
31760 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20  16_ALIGNED  8   
31770 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
31780 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c  te_collation onl
31790 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  y */../*.** CAPI
317a0 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 46  3REF: Function F
317b0 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  lags.**.** These
317c0 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62   constants may b
317d0 65 20 4f 52 65 64 20 74 6f 67 65 74 68 65 72 20  e ORed together 
317e0 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51  with the .** [SQ
317f0 4c 49 54 45 5f 55 54 46 38 20 7c 20 70 72 65 66  LITE_UTF8 | pref
31800 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
31810 69 6e 67 5d 20 61 73 20 74 68 65 20 66 6f 75 72  ing] as the four
31820 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  th argument.** t
31830 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
31840 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b  e_function()], [
31850 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
31860 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72  unction16()], or
31870 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
31880 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
31890 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
318a0 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53  QLITE_DETERMINIS
318b0 54 49 43 20 20 20 20 30 78 38 30 30 0a 0a 2f 2a  TIC    0x800../*
318c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
318d0 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f  precated Functio
318e0 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44  ns.** DEPRECATED
318f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
31900 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72  ctions are [depr
31910 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64  ecated].  In ord
31920 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a  er to maintain.*
31930 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
31940 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f  atibility with o
31950 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65  lder code, these
31960 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69   functions conti
31970 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75  nue .** to be su
31980 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65  pported.  Howeve
31990 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  r, new applicati
319a0 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64  ons should avoid
319b0 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74  .** the use of t
319c0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
319d0 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61   To help encoura
319e0 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f  ge people to avo
319f0 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73  id.** using thes
31a00 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20  e functions, we 
31a10 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f  are not going to
31a20 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74   tell you what t
31a30 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64  hey do..*/.#ifnd
31a40 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44  ef SQLITE_OMIT_D
31a50 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45  EPRECATED.SQLITE
31a60 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
31a70 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
31a80 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  e_count(sqlite3_
31a90 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54  context*);.SQLIT
31aa0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
31ab0 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64   sqlite3_expired
31ac0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
31ad0 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
31ae0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  ED int sqlite3_t
31af0 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73  ransfer_bindings
31b00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
31b10 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
31b20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
31b30 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c  D int sqlite3_gl
31b40 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69  obal_recover(voi
31b50 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  d);.SQLITE_DEPRE
31b60 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74  CATED void sqlit
31b70 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75  e3_thread_cleanu
31b80 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  p(void);.SQLITE_
31b90 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
31ba0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c  qlite3_memory_al
31bb0 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64  arm(void(*)(void
31bc0 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c  *,sqlite3_int64,
31bd0 69 6e 74 29 2c 0a 20 20 20 20 20 20 20 20 20 20  int),.          
31be0 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
31bf0 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
31c00 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ;.#endif../*.** 
31c10 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
31c20 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ing SQL Function
31c30 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65   Parameter Value
31c40 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61  s.**.** The C-la
31c50 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74  nguage implement
31c60 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e  ation of SQL fun
31c70 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
31c80 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68  gates uses.** th
31c90 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66  is set of interf
31ca0 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ace routines to 
31cb0 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d  access the param
31cc0 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a  eter values on.*
31cd0 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f  * the function o
31ce0 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a  r aggregate..**.
31cf0 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f  ** The xFunc (fo
31d00 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f  r scalar functio
31d10 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f  ns) or xStep (fo
31d20 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61  r aggregates) pa
31d30 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b  rameters.** to [
31d40 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
31d50 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
31d60 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
31d70 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
31d80 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73  define callbacks
31d90 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
31da0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
31db0 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
31dc0 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72  ..** The 3rd par
31dd0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20  ameter to these 
31de0 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20  callbacks is an 
31df0 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
31e00 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74  s to.** [protect
31e10 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
31e20 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72  ] objects.  Ther
31e30 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65  e is one [sqlite
31e40 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
31e50 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61  for.** each para
31e60 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c  meter to the SQL
31e70 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73   function.  Thes
31e80 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
31e90 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63  sed to.** extrac
31ea0 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68  t values from th
31eb0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
31ec0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a  ] objects..**.**
31ed0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
31ee0 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b  work only with [
31ef0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
31f00 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
31f10 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
31f20 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f   to use these ro
31f30 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e  utines on an [un
31f40 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
31f50 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65  3_value].** obje
31f60 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e  ct results in un
31f70 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
31f80 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
31f90 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73  outines work jus
31fa0 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65  t like the corre
31fb0 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e  sponding [column
31fc0 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
31fd0 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  s].** except tha
31fe0 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  t  these routine
31ff0 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20  s take a single 
32000 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
32010 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
32020 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74  .** pointer inst
32030 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65  ead of a [sqlite
32040 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72  3_stmt*] pointer
32050 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20   and an integer 
32060 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a  column number..*
32070 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
32080 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
32090 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61   interface extra
320a0 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72  cts a UTF-16 str
320b0 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  ing.** in the na
320c0 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20  tive byte-order 
320d0 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68  of the host mach
320e0 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ine.  ^The.** sq
320f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
32100 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74  16be() and sqlit
32110 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
32120 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
32130 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36  * extract UTF-16
32140 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d   strings as big-
32150 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c  endian and littl
32160 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74  e-endian respect
32170 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ively..**.** ^(T
32180 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
32190 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20  _numeric_type() 
321a0 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
321b0 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e  ts to apply.** n
321c0 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20  umeric affinity 
321d0 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54  to the value.  T
321e0 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61  his means that a
321f0 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20  n attempt is.** 
32200 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20  made to convert 
32210 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20  the value to an 
32220 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74  integer or float
32230 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a  ing point.  If.*
32240 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73  * such a convers
32250 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20  ion is possible 
32260 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20  without loss of 
32270 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20  information (in 
32280 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20  other.** words, 
32290 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  if the value is 
322a0 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f  a string that lo
322b0 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65  oks like a numbe
322c0 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  r).** then the c
322d0 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72  onversion is per
322e0 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69  formed.  Otherwi
322f0 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e  se no conversion
32300 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20   occurs..** The 
32310 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
32320 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65  | datatype] afte
32330 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  r conversion is 
32340 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  returned.)^.**.*
32350 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72  * Please pay par
32360 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f  ticular attentio
32370 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68  n to the fact th
32380 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72  at the pointer r
32390 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  eturned.** from 
323a0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
323b0 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
323c0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20  _value_text()], 
323d0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  or.** [sqlite3_v
323e0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63  alue_text16()] c
323f0 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  an be invalidate
32400 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e  d by a subsequen
32410 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
32420 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
32430 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  s()], [sqlite3_v
32440 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c  alue_bytes16()],
32450 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
32460 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
32470 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
32480 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  xt16()]..**.** T
32490 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
324a0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
324b0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
324c0 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20  d as.** the SQL 
324d0 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75  function that su
324e0 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69  pplied the [sqli
324f0 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61  te3_value*] para
32500 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74  meters..*/.const
32510 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
32520 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65  alue_blob(sqlite
32530 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
32540 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
32550 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  es(sqlite3_value
32560 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
32570 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71  value_bytes16(sq
32580 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64  lite3_value*);.d
32590 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61  ouble sqlite3_va
325a0 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  lue_double(sqlit
325b0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
325c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
325d0 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
325e0 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
325f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
32600 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c  nt64(sqlite3_val
32610 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69  ue*);.const unsi
32620 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
32630 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71  e3_value_text(sq
32640 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
32650 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
32660 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
32670 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
32680 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
32690 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
326a0 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6le(sqlite3_valu
326b0 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
326c0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
326d0 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
326e0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
326f0 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
32700 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
32710 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
32720 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
32730 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
32740 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32750 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61  : Obtain Aggrega
32760 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  te Function Cont
32770 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d  ext.**.** Implem
32780 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67  entations of agg
32790 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
327a0 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a  ions use this.**
327b0 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f   routine to allo
327c0 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20  cate memory for 
327d0 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74  storing their st
327e0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ate..**.** ^The 
327f0 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73  first time the s
32800 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
32810 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f  _context(C,N) ro
32820 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
32830 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63  .** for a partic
32840 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66  ular aggregate f
32850 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a  unction, SQLite.
32860 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f  ** allocates N o
32870 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73  f memory, zeroes
32880 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79   out that memory
32890 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  , and returns a 
328a0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
328b0 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f  e new memory. ^O
328c0 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  n second and sub
328d0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
328e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
328f0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
32900 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67  for the same agg
32910 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
32920 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65  instance,.** the
32930 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20   same buffer is 
32940 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74  returned.  Sqlit
32950 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
32960 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c  text() is normal
32970 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63  ly.** called onc
32980 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63  e for each invoc
32990 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74  ation of the xSt
329a0 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20  ep callback and 
329b0 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74  then one.** last
329c0 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78   time when the x
329d0 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69  Final callback i
329e0 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68  s invoked.  ^(Wh
329f0 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68  en no rows match
32a00 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65  .** an aggregate
32a10 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65   query, the xSte
32a20 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20  p() callback of 
32a30 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75  the aggregate fu
32a40 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  nction.** implem
32a50 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65  entation is neve
32a60 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69  r called and xFi
32a70 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20  nal() is called 
32a80 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a  exactly once..**
32a90 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c   In those cases,
32aa0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
32ab0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67  te_context() mig
32ac0 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72  ht be called for
32ad0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69   the.** first ti
32ae0 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78  me from within x
32af0 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a  Final().)^.**.**
32b00 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67   ^The sqlite3_ag
32b10 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
32b20 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74  C,N) routine ret
32b30 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
32b40 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72  ter .** when fir
32b50 73 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 69  st called if N i
32b60 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  s less than or e
32b70 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20  qual to zero or 
32b80 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  if a memory.** a
32b90 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63  llocate error oc
32ba0 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  curs..**.** ^(Th
32bb0 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63  e amount of spac
32bc0 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73  e allocated by s
32bd0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
32be0 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73  _context(C,N) is
32bf0 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62  .** determined b
32c00 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65  y the N paramete
32c10 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65  r on first succe
32c20 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61  ssful call.  Cha
32c30 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c  nging the.** val
32c40 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65  ue of N in subse
32c50 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
32c60 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
32c70 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e  context() within
32c80 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67  .** the same agg
32c90 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
32ca0 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f  instance will no
32cb0 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d  t resize the mem
32cc0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
32cd0 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68 65  n.)^  Within the
32ce0 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
32cf0 2c 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61 72  , it is customar
32d00 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20  y to set.** N=0 
32d10 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  in calls to sqli
32d20 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
32d30 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 68  ntext(C,N) so th
32d40 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c  at no .** pointl
32d50 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ess memory alloc
32d60 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a  ations occur..**
32d70 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f  .** ^SQLite auto
32d80 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20  matically frees 
32d90 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
32da0 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69  ated by .** sqli
32db0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
32dc0 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65  ntext() when the
32dd0 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
32de0 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a   concludes..**.*
32df0 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
32e00 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20  meter must be a 
32e10 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  copy of the.** [
32e20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
32e30 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  | SQL function c
32e40 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20  ontext] that is 
32e50 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
32e60 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53  ter.** to the xS
32e70 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  tep or xFinal ca
32e80 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74  llback routine t
32e90 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
32ea0 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20  he aggregate.** 
32eb0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
32ec0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
32ed0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
32ee0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
32ef0 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
32f00 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
32f10 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
32f20 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
32f30 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
32f40 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  ontext(sqlite3_c
32f50 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79  ontext*, int nBy
32f60 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tes);../*.** CAP
32f70 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61  I3REF: User Data
32f80 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   For Functions.*
32f90 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
32fa0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e  3_user_data() in
32fb0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
32fc0 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
32fd0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61   pointer that wa
32fe0 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20  s the pUserData 
32ff0 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35  parameter (the 5
33000 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  th parameter).**
33010 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
33020 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
33030 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
33040 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
33050 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
33060 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
33070 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
33080 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
33090 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
330a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
330b0 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
330c0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
330d0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
330e0 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  h.** the applica
330f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
33100 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
33110 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
33120 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c  e3_user_data(sql
33130 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
33140 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33150 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
33160 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f  tion For Functio
33170 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ns.**.** ^The sq
33180 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
33190 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66  _handle() interf
331a0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
331b0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
331c0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74  nter to the [dat
331d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
331e0 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d  ] (the 1st param
331f0 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
33200 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
33210 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
33220 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
33230 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
33240 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
33250 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
33260 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
33270 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
33280 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c  function..*/.sql
33290 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f  ite3 *sqlite3_co
332a0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
332b0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
332c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
332d0 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78  EF: Function Aux
332e0 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a  iliary Data.**.*
332f0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
33300 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79  s may be used by
33310 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65 29   (non-aggregate)
33320 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74   SQL functions t
33330 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d  o.** associate m
33340 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67  etadata with arg
33350 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66  ument values. If
33360 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20   the same value 
33370 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  is passed to.** 
33380 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74  multiple invocat
33390 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
333a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75   SQL function du
333b0 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75  ring query execu
333c0 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73  tion, under.** s
333d0 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ome circumstance
333e0 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64  s the associated
333f0 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65   metadata may be
33400 20 70 72 65 73 65 72 76 65 64 2e 20 20 41 6e 20   preserved.  An 
33410 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 68  example.** of wh
33420 65 72 65 20 74 68 69 73 20 6d 69 67 68 74 20 62  ere this might b
33430 65 20 75 73 65 66 75 6c 20 69 73 20 69 6e 20 61  e useful is in a
33440 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73   regular-express
33450 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a 2a 2a 20  ion matching.** 
33460 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f  function. The co
33470 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f  mpiled version o
33480 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  f the regular ex
33490 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20  pression can be 
334a0 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74  stored as.** met
334b0 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64  adata associated
334c0 20 77 69 74 68 20 74 68 65 20 70 61 74 74 65 72   with the patter
334d0 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a 2a 20 54  n string.  .** T
334e0 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  hen as long as t
334f0 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e  he pattern strin
33500 67 20 72 65 6d 61 69 6e 73 20 74 68 65 20 73 61  g remains the sa
33510 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d 70 69  me,.** the compi
33520 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72  led regular expr
33530 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65  ession can be re
33540 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65  used on multiple
33550 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
33560 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
33570 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
33580 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
33590 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
335a0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
335b0 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61  er to the metada
335c0 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ta.** associated
335d0 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
335e0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75  set_auxdata() fu
335f0 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20  nction with the 
33600 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  Nth argument.** 
33610 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70  value to the app
33620 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
33630 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 74   function. ^If t
33640 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64  here is no metad
33650 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
33660 64 20 77 69 74 68 20 74 68 65 20 66 75 6e 63 74  d with the funct
33670 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c 20 74 68  ion argument, th
33680 69 73 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  is sqlite3_get_a
33690 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
336a0 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ce.** returns a 
336b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
336c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
336d0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _set_auxdata(C,N
336e0 2c 50 2c 58 29 20 69 6e 74 65 72 66 61 63 65 20  ,P,X) interface 
336f0 73 61 76 65 73 20 50 20 61 73 20 6d 65 74 61 64  saves P as metad
33700 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68  ata for the N-th
33710 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  .** argument of 
33720 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
33730 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
33740 2e 20 20 5e 53 75 62 73 65 71 75 65 6e 74 0a 2a  .  ^Subsequent.*
33750 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
33760 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43  e3_get_auxdata(C
33770 2c 4e 29 20 72 65 74 75 72 6e 20 50 20 66 72 6f  ,N) return P fro
33780 6d 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  m the most recen
33790 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74  t.** sqlite3_set
337a0 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58  _auxdata(C,N,P,X
337b0 29 20 63 61 6c 6c 20 69 66 20 74 68 65 20 6d 65  ) call if the me
337c0 74 61 64 61 74 61 20 69 73 20 73 74 69 6c 6c 20  tadata is still 
337d0 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c  valid or.** NULL
337e0 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 74 61   if the metadata
337f0 20 68 61 73 20 62 65 65 6e 20 64 69 73 63 61 72   has been discar
33800 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65 72 20 65  ded..** ^After e
33810 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ach call to sqli
33820 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
33830 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72 65 20 58  C,N,P,X) where X
33840 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a   is not NULL,.**
33850 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76   SQLite will inv
33860 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74  oke the destruct
33870 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69  or function X wi
33880 74 68 20 70 61 72 61 6d 65 74 65 72 20 50 20 65  th parameter P e
33890 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20  xactly.** once, 
338a0 77 68 65 6e 20 74 68 65 20 6d 65 74 61 64 61 74  when the metadat
338b0 61 20 69 73 20 64 69 73 63 61 72 64 65 64 2e 0a  a is discarded..
338c0 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65  ** SQLite is fre
338d0 65 20 74 6f 20 64 69 73 63 61 72 64 20 74 68 65  e to discard the
338e0 20 6d 65 74 61 64 61 74 61 20 61 74 20 61 6e 79   metadata at any
338f0 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64 69 6e 67   time, including
33900 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77  : <ul>.** <li> w
33910 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
33920 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70  nding function p
33930 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73  arameter changes
33940 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65  , or.** <li> whe
33950 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
33960 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
33970 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63  finalize()] is c
33980 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a  alled for the.**
33990 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d        SQL statem
339a0 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  ent, or.** <li> 
339b0 77 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 65 74  when sqlite3_set
339c0 5f 61 75 78 64 61 74 61 28 29 20 69 73 20 69 6e  _auxdata() is in
339d0 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  voked again on t
339e0 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65  he same paramete
339f0 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75  r, or.** <li> du
33a00 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61  ring the origina
33a10 6c 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  l sqlite3_set_au
33a20 78 64 61 74 61 28 29 20 63 61 6c 6c 20 77 68 65  xdata() call whe
33a30 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20  n a memory .**  
33a40 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65      allocation e
33a50 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 3c 2f 75  rror occurs. </u
33a60 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  l>)^.**.** Note 
33a70 74 68 65 20 6c 61 73 74 20 62 75 6c 6c 65 74 20  the last bullet 
33a80 69 6e 20 70 61 72 74 69 63 75 6c 61 72 2e 20 20  in particular.  
33a90 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 58  The destructor X
33aa0 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   in .** sqlite3_
33ab0 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
33ac0 50 2c 58 29 20 6d 69 67 68 74 20 62 65 20 63 61  P,X) might be ca
33ad0 6c 6c 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  lled immediately
33ae0 2c 20 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20  , before the.** 
33af0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
33b00 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
33b10 65 76 65 6e 20 72 65 74 75 72 6e 73 2e 20 20 48  even returns.  H
33b20 65 6e 63 65 20 73 71 6c 69 74 65 33 5f 73 65 74  ence sqlite3_set
33b30 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a 20 73 68  _auxdata().** sh
33b40 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65 64 20 6e  ould be called n
33b50 65 61 72 20 74 68 65 20 65 6e 64 20 6f 66 20 74  ear the end of t
33b60 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  he function impl
33b70 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 20 74  ementation and t
33b80 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  he.** function i
33b90 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68  mplementation sh
33ba0 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b 65 20 61 6e  ould not make an
33bb0 79 20 75 73 65 20 6f 66 20 50 20 61 66 74 65 72  y use of P after
33bc0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  .** sqlite3_set_
33bd0 61 75 78 64 61 74 61 28 29 20 68 61 73 20 62 65  auxdata() has be
33be0 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a  en called..**.**
33bf0 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20   ^(In practice, 
33c00 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73  metadata is pres
33c10 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75  erved between fu
33c20 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72  nction calls for
33c30 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  .** function par
33c40 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65  ameters that are
33c50 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f   compile-time co
33c60 6e 73 74 61 6e 74 73 2c 20 69 6e 63 6c 75 64 69  nstants, includi
33c70 6e 67 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61  ng literal.** va
33c80 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65  lues and [parame
33c90 74 65 72 73 5d 20 61 6e 64 20 65 78 70 72 65 73  ters] and expres
33ca0 73 69 6f 6e 73 20 63 6f 6d 70 6f 73 65 64 20 66  sions composed f
33cb0 72 6f 6d 20 74 68 65 20 73 61 6d 65 2e 29 5e 0a  rom the same.)^.
33cc0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
33cd0 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
33ce0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
33cf0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
33d00 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  h.** the SQL fun
33d10 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
33d20 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
33d30 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73  e3_get_auxdata(s
33d40 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33d50 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71   int N);.void sq
33d60 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
33d70 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
33d80 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a  t*, int N, void*
33d90 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a  , void (*)(void*
33da0 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ));.../*.** CAPI
33db0 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20  3REF: Constants 
33dc0 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c  Defining Special
33dd0 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61   Destructor Beha
33de0 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  vior.**.** These
33df0 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c   are special val
33e00 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74  ues for the dest
33e10 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70  ructor that is p
33e20 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a  assed in as the.
33e30 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e  ** final argumen
33e40 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  t to routines li
33e50 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ke [sqlite3_resu
33e60 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66  lt_blob()].  ^If
33e70 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a   the destructor.
33e80 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53  ** argument is S
33e90 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74  QLITE_STATIC, it
33ea0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
33eb0 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20  content pointer 
33ec0 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61  is constant.** a
33ed0 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68  nd will never ch
33ee0 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e  ange.  It does n
33ef0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65  ot need to be de
33f00 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a  stroyed.  ^The.*
33f10 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  * SQLITE_TRANSIE
33f20 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74  NT value means t
33f30 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
33f40 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e  will likely chan
33f50 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61  ge in.** the nea
33f60 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61  r future and tha
33f70 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20  t SQLite should 
33f80 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69  make its own pri
33f90 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  vate copy of.** 
33fa0 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f  the content befo
33fb0 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a  re returning..**
33fc0 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20  .** The typedef 
33fd0 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20  is necessary to 
33fe0 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62  work around prob
33ff0 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a  lems in certain.
34000 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73  ** C++ compilers
34010 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69  ..*/.typedef voi
34020 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74  d (*sqlite3_dest
34030 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69  ructor_type)(voi
34040 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c  d*);.#define SQL
34050 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20  ITE_STATIC      
34060 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
34070 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65  ctor_type)0).#de
34080 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
34090 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65  SIENT   ((sqlite
340a0 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
340b0 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e)-1)../*.** CAP
340c0 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54  I3REF: Setting T
340d0 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20  he Result Of An 
340e0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a  SQL Function.**.
340f0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
34100 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68  s are used by th
34110 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61  e xFunc or xFina
34120 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  l callbacks that
34130 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51  .** implement SQ
34140 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
34150 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65  aggregates.  See
34160 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
34170 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
34180 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
34190 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
341a0 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f  ].** for additio
341b0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
341c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
341d0 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79  ctions work very
341e0 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b   much like the [
341f0 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
34200 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  g] family of.** 
34210 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74  functions used t
34220 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  o bind values to
34230 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
34240 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61   in prepared sta
34250 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65  tements..** Refe
34260 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61  r to the [SQL pa
34270 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e  rameter] documen
34280 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74  tation for addit
34290 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
342a0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  n..**.** ^The sq
342b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
342c0 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  b() interface se
342d0 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
342e0 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
342f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
34300 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
34310 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65  BLOB whose conte
34320 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a  nt is pointed.**
34330 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e   to by the secon
34340 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  d parameter and 
34350 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73  which is N bytes
34360 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73   long where N is
34370 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61   the.** third pa
34380 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  rameter..**.** ^
34390 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
343a0 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e  lt_zeroblob() in
343b0 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68 65  terfaces set the
343c0 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68   result of.** th
343d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
343e0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
343f0 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74  o be a BLOB cont
34400 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a  aining all zero.
34410 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62  ** bytes and N b
34420 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68  ytes in size, wh
34430 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c  ere N is the val
34440 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61  ue of the 2nd pa
34450 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  rameter..**.** ^
34460 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
34470 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65  lt_double() inte
34480 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
34490 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
344a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
344b0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
344c0 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70   be a floating p
344d0 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69  oint value speci
344e0 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32  fied.** by its 2
344f0 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
34500 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34510 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
34520 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
34530 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63  t_error16() func
34540 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74  tions.** cause t
34550 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53  he implemented S
34560 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74  QL function to t
34570 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f  hrow an exceptio
34580 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  n..** ^SQLite us
34590 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f  es the string po
345a0 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a  inted to by the.
345b0 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ** 2nd parameter
345c0 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75   of sqlite3_resu
345d0 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71  lt_error() or sq
345e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
345f0 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65  or16().** as the
34600 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f   text of an erro
34610 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c  r message.  ^SQL
34620 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74  ite interprets t
34630 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  he error.** mess
34640 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  age string from 
34650 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
34660 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e  rror() as UTF-8.
34670 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65   ^SQLite.** inte
34680 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e  rprets the strin
34690 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72  g from sqlite3_r
346a0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
346b0 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  as UTF-16 in nat
346c0 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65  ive.** byte orde
346d0 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69 72  r.  ^If the thir
346e0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
346f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
34700 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ror().** or sqli
34710 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
34720 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 65  16() is negative
34730 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
34740 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a  es as the error.
34750 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74  ** message all t
34760 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 74  ext up through t
34770 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
34780 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  aracter..** ^If 
34790 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
347a0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
347b0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72  esult_error() or
347c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
347d0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
347e0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65  non-negative the
347f0 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74  n SQLite takes t
34800 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65  hat many.** byte
34810 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
34820 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  s) from the 2nd 
34830 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
34840 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
34850 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34860 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
34870 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
34880 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72  t_error16().** r
34890 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70  outines make a p
348a0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
348b0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
348c0 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20   text before.** 
348d0 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65  they return.  He
348e0 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  nce, the calling
348f0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65   function can de
34900 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d  allocate or.** m
34910 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61  odify the text a
34920 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e  fter they return
34930 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a   without harm..*
34940 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
34950 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
34960 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e  () function chan
34970 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f  ges the error co
34980 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  de.** returned b
34990 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65  y SQLite as a re
349a0 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72  sult of an error
349b0 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20   in a function. 
349c0 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a   ^By default,.**
349d0 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
349e0 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  is SQLITE_ERROR.
349f0 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20    ^A subsequent 
34a00 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
34a10 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a  result_error().*
34a20 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
34a30 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65  ult_error16() re
34a40 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 63  sets the error c
34a50 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52  ode to SQLITE_ER
34a60 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ROR..**.** ^The 
34a70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
34a80 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e  rror_toobig() in
34a90 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
34aa0 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61  QLite to throw a
34ab0 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63  n.** error indic
34ac0 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72  ating that a str
34ad0 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74  ing or BLOB is t
34ae0 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65  oo long to repre
34af0 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  sent..**.** ^The
34b00 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34b10 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e  error_nomem() in
34b20 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
34b30 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61  QLite to throw a
34b40 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63  n.** error indic
34b50 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d  ating that a mem
34b60 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
34b70 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ailed..**.** ^Th
34b80 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
34b90 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65  _int() interface
34ba0 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
34bb0 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
34bc0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
34bd0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
34be0 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73   be the 32-bit s
34bf0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
34c00 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20   value given in 
34c10 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  the 2nd argument
34c20 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
34c30 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29  3_result_int64()
34c40 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
34c50 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
34c60 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
34c70 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
34c80 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
34c90 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  e 64-bit signed 
34ca0 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
34cb0 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
34cc0 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
34cd0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
34ce0 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74  esult_null() int
34cf0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
34d00 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
34d10 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
34d20 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
34d30 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a  ion to be NULL..
34d40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
34d50 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29  e3_result_text()
34d60 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  , sqlite3_result
34d70 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71  _text16(),.** sq
34d80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
34d90 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c  t16le(), and sql
34da0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
34db0 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65  16be() interface
34dc0 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74  s.** set the ret
34dd0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65  urn value of the
34de0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
34df0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
34e00 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74   be.** a text st
34e10 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65  ring which is re
34e20 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46  presented as UTF
34e30 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76  -8, UTF-16 nativ
34e40 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a  e byte order,.**
34e50 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65   UTF-16 little e
34e60 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36  ndian, or UTF-16
34e70 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73   big endian, res
34e80 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53  pectively..** ^S
34e90 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20  QLite takes the 
34ea0 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d  text result from
34eb0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
34ec0 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64   from.** the 2nd
34ed0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68   parameter of th
34ee0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
34ef0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
34f00 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72  s..** ^If the 3r
34f10 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
34f20 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
34f30 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
34f40 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76  es.** is negativ
34f50 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  e, then SQLite t
34f60 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74  akes result text
34f70 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
34f80 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75  rameter.** throu
34f90 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
34fa0 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  o character..** 
34fb0 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61  ^If the 3rd para
34fc0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
34fd0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
34fe0 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
34ff0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
35000 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79   then as many by
35010 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74  tes (not charact
35020 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74  ers) of the text
35030 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
35040 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
35050 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73  ter are taken as
35060 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
35070 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63  -defined.** func
35080 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66  tion result.  If
35090 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
350a0 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  er is non-negati
350b0 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d  ve, then it.** m
350c0 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20  ust be the byte 
350d0 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20  offset into the 
350e0 73 74 72 69 6e 67 20 77 68 65 72 65 20 74 68 65  string where the
350f0 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20   NUL terminator 
35100 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20  would.** appear 
35110 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 77 68  if the string wh
35120 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74  ere NUL terminat
35130 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20  ed.  If any NUL 
35140 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72  characters occur
35150 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e  .** in the strin
35160 67 20 61 74 20 61 20 62 79 74 65 20 6f 66 66 73  g at a byte offs
35170 65 74 20 74 68 61 74 20 69 73 20 6c 65 73 73 20  et that is less 
35180 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f  than the value o
35190 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72  f the 3rd.** par
351a0 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65  ameter, then the
351b0 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
351c0 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65  g will contain e
351d0 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64  mbedded NULs and
351e0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f   the.** result o
351f0 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70  f expressions op
35200 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e  erating on strin
35210 67 73 20 77 69 74 68 20 65 6d 62 65 64 64 65 64  gs with embedded
35220 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e   NULs is undefin
35230 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  ed..** ^If the 4
35240 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
35250 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
35260 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
35270 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
35280 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
35290 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
352a0 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
352b0 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66   calls that.** f
352c0 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64  unction as the d
352d0 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65  estructor on the
352e0 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65   text or BLOB re
352f0 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73  sult when it has
35300 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69  .** finished usi
35310 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
35320 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
35330 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
35340 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
35350 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ext* interfaces 
35360 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  or to.** sqlite3
35370 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
35380 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73  the special cons
35390 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54  tant SQLITE_STAT
353a0 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a  IC, then SQLite.
353b0 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ** assumes that 
353c0 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42  the text or BLOB
353d0 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f   result is in co
353e0 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64  nstant space and
353f0 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70   does not.** cop
35400 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  y the content of
35410 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e   the parameter n
35420 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75  or call a destru
35430 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74  ctor on the cont
35440 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68  ent.** when it h
35450 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  as finished usin
35460 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
35470 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
35480 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
35490 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
354a0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
354b0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
354c0 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20  ult_blob is the 
354d0 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74  special constant
354e0 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
354f0 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65  T.** then SQLite
35500 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
35510 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f   the result into
35520 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20   space obtained 
35530 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  from.** from [sq
35540 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
35550 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e  before it return
35560 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
35570 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
35580 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ue() interface s
35590 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f  ets the result o
355a0 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
355b0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
355c0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f  ction to be a co
355d0 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f  py the.** [unpro
355e0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
355f0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65  alue] object spe
35600 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e  cified by the 2n
35610 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54  d parameter.  ^T
35620 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  he.** sqlite3_re
35630 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74  sult_value() int
35640 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63  erface makes a c
35650 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  opy of the [sqli
35660 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f  te3_value].** so
35670 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74   that the [sqlit
35680 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66  e3_value] specif
35690 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d  ied in the param
356a0 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20  eter may change 
356b0 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63  or.** be dealloc
356c0 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74  ated after sqlit
356d0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
356e0 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75  ) returns withou
356f0 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70  t harm..** ^A [p
35700 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
35710 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d  _value] object m
35720 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65  ay always be use
35730 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75  d where an.** [u
35740 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
35750 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
35760 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f   is required, so
35770 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20   either.** kind 
35780 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  of [sqlite3_valu
35790 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65  e] object can be
357a0 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20   used with this 
357b0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
357c0 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   If these routin
357d0 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  es are called fr
357e0 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69  om within the di
357f0 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a  fferent thread.*
35800 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63  * than the one c
35810 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70  ontaining the ap
35820 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
35830 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  d function that 
35840 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20  received.** the 
35850 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
35860 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72  ] pointer, the r
35870 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
35880 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  ined..*/.void sq
35890 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
358a0 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
358b0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
358c0 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
358d0 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
358e0 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
358f0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
35900 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69  t*, double);.voi
35910 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
35920 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63  _error(sqlite3_c
35930 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
35940 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  har*, int);.void
35950 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35960 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f  error16(sqlite3_
35970 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
35980 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  void*, int);.voi
35990 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
359a0 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71  _error_toobig(sq
359b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
359c0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
359d0 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
359e0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
359f0 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
35a00 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f  _result_error_co
35a10 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  de(sqlite3_conte
35a20 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  xt*, int);.void 
35a30 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
35a40 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
35a50 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  xt*, int);.void 
35a60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
35a70 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nt64(sqlite3_con
35a80 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69  text*, sqlite3_i
35a90 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69  nt64);.void sqli
35aa0 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
35ab0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35ac0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
35ad0 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69  result_text(sqli
35ae0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
35af0 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20  nst char*, int, 
35b00 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
35b10 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
35b20 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69  sult_text16(sqli
35b30 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
35b40 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
35b50 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
35b60 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
35b70 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71  sult_text16le(sq
35b80 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
35b90 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
35ba0 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
35bb0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
35bc0 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73  esult_text16be(s
35bd0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
35be0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
35bf0 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
35c00 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
35c10 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c  result_value(sql
35c20 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
35c30 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
35c40 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
35c50 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ult_zeroblob(sql
35c60 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
35c70 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
35c80 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e  PI3REF: Define N
35c90 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71  ew Collating Seq
35ca0 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  uences.**.** ^Th
35cb0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64  ese functions ad
35cc0 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f  d, remove, or mo
35cd0 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f  dify a [collatio
35ce0 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  n] associated.**
35cf0 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
35d00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
35d10 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65  specified as the
35d20 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
35d30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
35d40 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   of the collatio
35d50 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72  n is a UTF-8 str
35d60 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74  ing.** for sqlit
35d70 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
35d80 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ion() and sqlite
35d90 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
35da0 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61  on_v2().** and a
35db0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69   UTF-16 string i
35dc0 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
35dd0 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
35de0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
35df0 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74  16()..** ^Collat
35e00 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63  ion names that c
35e10 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63 63  ompare equal acc
35e20 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74  ording to [sqlit
35e30 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61  e3_strnicmp()] a
35e40 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64  re.** considered
35e50 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20   to be the same 
35e60 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  name..**.** ^(Th
35e70 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
35e80 20 28 65 54 65 78 74 52 65 70 29 20 6d 75 73 74   (eTextRep) must
35e90 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63   be one of the c
35ea0 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c  onstants:.** <ul
35eb0 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
35ec0 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e  E_UTF8],.** <li>
35ed0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
35ee0 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
35ef0 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20  TE_UTF16BE],.** 
35f00 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
35f10 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  16], or.** <li> 
35f20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c  [SQLITE_UTF16_AL
35f30 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  IGNED]..** </ul>
35f40 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74  )^.** ^The eText
35f50 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74  Rep argument det
35f60 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f  ermines the enco
35f70 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20  ding of strings 
35f80 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65  passed.** to the
35f90 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
35fa0 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43  ion callback, xC
35fb0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65  allback..** ^The
35fc0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20   [SQLITE_UTF16] 
35fd0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  and [SQLITE_UTF1
35fe0 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65  6_ALIGNED] value
35ff0 73 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a  s for eTextRep.*
36000 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20  * force strings 
36010 74 6f 20 62 65 20 55 54 46 31 36 20 77 69 74 68  to be UTF16 with
36020 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
36030 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  er..** ^The [SQL
36040 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
36050 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65  D] value for eTe
36060 78 74 52 65 70 20 66 6f 72 63 65 73 20 73 74 72  xtRep forces str
36070 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a  ings to begin.**
36080 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65   on an even byte
36090 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20   address..**.** 
360a0 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75  ^The fourth argu
360b0 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61  ment, pArg, is a
360c0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  n application da
360d0 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  ta pointer that 
360e0 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72  is passed.** thr
360f0 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73  ough as the firs
36100 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
36110 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
36120 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  tion callback..*
36130 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20  *.** ^The fifth 
36140 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62  argument, xCallb
36150 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65  ack, is a pointe
36160 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69  r to the collati
36170 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ng function..** 
36180 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74  ^Multiple collat
36190 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61  ing functions ca
361a0 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  n be registered 
361b0 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e  using the same n
361c0 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20  ame but.** with 
361d0 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52  different eTextR
361e0 65 70 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e  ep parameters an
361f0 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73  d SQLite will us
36200 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66  e whichever.** f
36210 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
36220 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e   the least amoun
36230 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66  t of data transf
36240 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66  ormation..** ^If
36250 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61   the xCallback a
36260 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20  rgument is NULL 
36270 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69  then the collati
36280 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a  ng function is.*
36290 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65  * deleted.  ^Whe
362a0 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20  n all collating 
362b0 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67  functions having
362c0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61   the same name a
362d0 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74  re deleted,.** t
362e0 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73  hat collation is
362f0 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c   no longer usabl
36300 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f  e..**.** ^The co
36310 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
36320 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
36330 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70 79  oked with a copy
36340 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a   of the pArg .**
36350 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
36360 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69  a pointer and wi
36370 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69  th two strings i
36380 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73  n the encoding s
36390 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74  pecified.** by t
363a0 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75  he eTextRep argu
363b0 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61  ment.  The colla
363c0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ting function mu
363d0 73 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20  st return an.** 
363e0 69 6e 74 65 67 65 72 20 74 68 61 74 20 69 73 20  integer that is 
363f0 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20  negative, zero, 
36400 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69  or positive.** i
36410 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69  f the first stri
36420 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c  ng is less than,
36430 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72   equal to, or gr
36440 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73  eater than the s
36450 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63  econd,.** respec
36460 74 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61  tively.  A colla
36470 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ting function mu
36480 73 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  st always return
36490 20 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72   the same answer
364a0 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61  .** given the sa
364b0 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74  me inputs.  If t
364c0 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61  wo or more colla
364d0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61  ting functions a
364e0 72 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a  re registered.**
364f0 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   to the same col
36500 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69  lation name (usi
36510 6e 67 20 64 69 66 66 65 72 65 6e 74 20 65 54 65  ng different eTe
36520 78 74 52 65 70 20 76 61 6c 75 65 73 29 20 74 68  xtRep values) th
36530 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67  en all.** must g
36540 69 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e  ive an equivalen
36550 74 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e  t answer when in
36560 76 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69 76  voked with equiv
36570 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a  alent strings..*
36580 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  * The collating 
36590 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62  function must ob
365a0 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ey the following
365b0 20 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20   properties for 
365c0 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41  all.** strings A
365d0 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a  , B, and C:.**.*
365e0 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49  * <ol>.** <li> I
365f0 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41  f A==B then B==A
36600 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d  ..** <li> If A==
36610 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20  B and B==C then 
36620 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66  A==C..** <li> If
36630 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67   A&lt;B THEN B&g
36640 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  t;A..** <li> If 
36650 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b  A&lt;B and B&lt;
36660 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a  C then A&lt;C..*
36670 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66  * </ol>.**.** If
36680 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e   a collating fun
36690 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20  ction fails any 
366a0 6f 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e  of the above con
366b0 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61  straints and tha
366c0 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66  t.** collating f
366d0 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69  unction is  regi
366e0 73 74 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c  stered and used,
366f0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
36700 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  or of SQLite.** 
36710 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
36720 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36730 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
36740 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b  n_v2() works lik
36750 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
36760 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20  _collation().** 
36770 77 69 74 68 20 74 68 65 20 61 64 64 69 74 69 6f  with the additio
36780 6e 20 74 68 61 74 20 74 68 65 20 78 44 65 73 74  n that the xDest
36790 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  roy callback is 
367a0 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20  invoked on pArg 
367b0 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c  when.** the coll
367c0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  ating function i
367d0 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43  s deleted..** ^C
367e0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
367f0 6e 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 77  ns are deleted w
36800 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65  hen they are ove
36810 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72  rridden by later
36820 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  .** calls to the
36830 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74   collation creat
36840 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  ion functions or
36850 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61   when the.** [da
36860 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36870 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69  n] is closed usi
36880 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ng [sqlite3_clos
36890 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  e()]..**.** ^The
368a0 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61   xDestroy callba
368b0 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e  ck is <u>not</u>
368c0 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a   called if the .
368d0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
368e0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
368f0 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e   function fails.
36900 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
36910 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  hat invoke.** sq
36920 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
36930 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68  lation_v2() with
36940 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73   a non-NULL xDes
36950 74 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68  troy argument sh
36960 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74  ould .** check t
36970 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 61  he return code a
36980 6e 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  nd dispose of th
36990 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
369a0 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68  ta pointer.** th
369b0 65 6d 73 65 6c 76 65 73 20 72 61 74 68 65 72 20  emselves rather 
369c0 74 68 61 6e 20 65 78 70 65 63 74 69 6e 67 20 53  than expecting S
369d0 51 4c 69 74 65 20 74 6f 20 64 65 61 6c 20 77 69  QLite to deal wi
369e0 74 68 20 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a  th it for them..
369f0 2a 2a 20 54 68 69 73 20 69 73 20 64 69 66 66 65  ** This is diffe
36a00 72 65 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 20  rent from every 
36a10 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
36a20 65 72 66 61 63 65 2e 20 20 54 68 65 20 69 6e 63  erface.  The inc
36a30 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69  onsistency .** i
36a40 73 20 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 75  s unfortunate bu
36a50 74 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e  t cannot be chan
36a60 67 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  ged without brea
36a70 6b 69 6e 67 20 62 61 63 6b 77 61 72 64 73 20 0a  king backwards .
36a80 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
36a90 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
36aa0 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  :  [sqlite3_coll
36ab0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20  ation_needed()] 
36ac0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
36ad0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
36ae0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
36af0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
36b00 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ion(.  sqlite3*,
36b10 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a   .  const char *
36b20 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54  zName, .  int eT
36b30 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20  extRep, .  void 
36b40 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43  *pArg,.  int(*xC
36b50 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
36b60 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
36b70 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  t,const void*).)
36b80 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
36b90 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
36ba0 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  2(.  sqlite3*, .
36bb0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
36bc0 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
36bd0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70  tRep, .  void *p
36be0 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  Arg,.  int(*xCom
36bf0 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
36c00 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
36c10 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20  const void*),.  
36c20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
36c30 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  void*).);.int sq
36c40 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
36c50 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69  lation16(.  sqli
36c60 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76  te3*, .  const v
36c70 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e  oid *zName,.  in
36c80 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
36c90 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74  oid *pArg,.  int
36ca0 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
36cb0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
36cc0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
36cd0 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
36ce0 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e  I3REF: Collation
36cf0 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b   Needed Callback
36d00 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69  s.**.** ^To avoi
36d10 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69  d having to regi
36d20 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69  ster all collati
36d30 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66  on sequences bef
36d40 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a  ore a database.*
36d50 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61  * can be used, a
36d60 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b   single callback
36d70 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
36d80 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
36d90 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
36da0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
36db0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
36dc0 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65  ever an undefine
36dd0 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  d collation.** s
36de0 65 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69  equence is requi
36df0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  red..**.** ^If t
36e00 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
36e10 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
36e20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  the sqlite3_coll
36e30 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41  ation_needed() A
36e40 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  PI,.** then it i
36e50 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d  s passed the nam
36e60 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20  es of undefined 
36e70 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
36e80 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a  ces as strings.*
36e90 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46  * encoded in UTF
36ea0 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  -8. ^If sqlite3_
36eb0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
36ec0 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a  16() is used,.**
36ed0 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70   the names are p
36ee0 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20  assed as UTF-16 
36ef0 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76  in machine nativ
36f00 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
36f10 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68   ^A call to eith
36f20 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c  er function repl
36f30 61 63 65 73 20 74 68 65 20 65 78 69 73 74 69 6e  aces the existin
36f40 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64  g collation-need
36f50 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  ed callback..**.
36f60 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61  ** ^(When the ca
36f70 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
36f80 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67  d, the first arg
36f90 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20  ument passed is 
36fa0 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65  a copy.** of the
36fb0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
36fc0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c   to sqlite3_coll
36fd0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f  ation_needed() o
36fe0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
36ff0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
37000 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61  ).  The second a
37010 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64  rgument is the d
37020 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
37030 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72  ction.  The thir
37040 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  d argument is on
37050 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46  e of [SQLITE_UTF
37060 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  8], [SQLITE_UTF1
37070 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  6BE],.** or [SQL
37080 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e  ITE_UTF16LE], in
37090 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73  dicating the mos
370a0 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d  t desirable form
370b0 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   of the collatio
370c0 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75  n.** sequence fu
370d0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e  nction required.
370e0 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72    The fourth par
370f0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
37100 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71  me of the.** req
37110 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  uired collation 
37120 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a  sequence.)^.**.*
37130 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  * The callback f
37140 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72  unction should r
37150 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69  egister the desi
37160 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73  red collation us
37170 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
37180 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
37190 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
371a0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
371b0 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
371c0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
371d0 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69  tion_v2()]..*/.i
371e0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
371f0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73  tion_needed(.  s
37200 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
37210 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  *, .  void(*)(vo
37220 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74  id*,sqlite3*,int
37230 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20   eTextRep,const 
37240 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  char*).);.int sq
37250 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
37260 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69  needed16(.  sqli
37270 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  te3*, .  void*,.
37280 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
37290 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
372a0 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64  xtRep,const void
372b0 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 51  *).);..#ifdef SQ
372c0 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f  LITE_HAS_CODEC./
372d0 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
372e0 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72   key for an encr
372f0 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  ypted database. 
37300 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68   This routine sh
37310 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65  ould be.** calle
37320 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71  d right after sq
37330 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a  lite3_open()..**
37340 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
37350 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
37360 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
37370 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
37380 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
37390 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
373a0 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71  qlite3_key(.  sq
373b0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
373c0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
373d0 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
373e0 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
373f0 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
37400 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
37410 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 69 6e 74 20  e key */.);.int 
37420 73 71 6c 69 74 65 33 5f 6b 65 79 5f 76 32 28 0a  sqlite3_key_v2(.
37430 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
37440 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37450 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
37460 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
37470 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e  const char *zDbN
37480 61 6d 65 2c 20 20 20 20 20 20 20 20 20 20 20 2f  ame,           /
37490 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  * Name of the da
374a0 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
374b0 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
374c0 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
374d0 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  e key */.);../*.
374e0 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65  ** Change the ke
374f0 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74  y on an open dat
37500 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63  abase.  If the c
37510 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20  urrent database 
37520 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70  is not.** encryp
37530 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  ted, this routin
37540 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69  e will encrypt i
37550 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f  t.  If pNew==0 o
37560 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a  r nNew==0, the.*
37570 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65  * database is de
37580 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  crypted..**.** T
37590 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
375a0 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
375b0 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
375c0 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
375d0 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
375e0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
375f0 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74  3_rekey(.  sqlit
37600 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
37610 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
37620 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
37630 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
37640 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
37650 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e  Key     /* The n
37660 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 69 6e 74  ew key */.);.int
37670 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 5f 76   sqlite3_rekey_v
37680 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
37690 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
376a0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
376b0 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
376c0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
376d0 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20  DbName,         
376e0 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
376f0 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
37700 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
37710 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
37720 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a   The new key */.
37730 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  );../*.** Specif
37740 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e  y the activation
37750 20 6b 65 79 20 66 6f 72 20 61 20 53 45 45 20 64   key for a SEE d
37760 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73  atabase.  Unless
37770 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20   .** activated, 
37780 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 45 45 20  none of the SEE 
37790 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f  routines will wo
377a0 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  rk..*/.void sqli
377b0 74 65 33 5f 61 63 74 69 76 61 74 65 5f 73 65 65  te3_activate_see
377c0 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
377d0 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20  zPassPhrase     
377e0 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e     /* Activation
377f0 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65   phrase */.);.#e
37800 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 53 51 4c  ndif..#ifdef SQL
37810 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44  ITE_ENABLE_CEROD
37820 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
37830 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65  he activation ke
37840 79 20 66 6f 72 20 61 20 43 45 52 4f 44 20 64 61  y for a CEROD da
37850 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20  tabase.  Unless 
37860 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e  .** activated, n
37870 6f 6e 65 20 6f 66 20 74 68 65 20 43 45 52 4f 44  one of the CEROD
37880 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77   routines will w
37890 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ork..*/.void sql
378a0 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 63 65  ite3_activate_ce
378b0 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  rod(.  const cha
378c0 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20  r *zPassPhrase  
378d0 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74        /* Activat
378e0 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b  ion phrase */.);
378f0 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
37900 41 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64  API3REF: Suspend
37910 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41   Execution For A
37920 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a   Short Time.**.*
37930 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c  * The sqlite3_sl
37940 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  eep() function c
37950 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e  auses the curren
37960 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70  t thread to susp
37970 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a  end execution.**
37980 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20   for at least a 
37990 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
379a0 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64  econds specified
379b0 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65   in its paramete
379c0 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  r..**.** If the 
379d0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
379e0 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72   does not suppor
379f0 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73  t sleep requests
37a00 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65   with.** millise
37a10 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75  cond time resolu
37a20 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74  tion, then the t
37a30 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e  ime will be roun
37a40 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65  ded up to.** the
37a50 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e   nearest second.
37a60 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   The number of m
37a70 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
37a80 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a  leep actually.**
37a90 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20   requested from 
37aa0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
37ab0 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64  stem is returned
37ac0 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
37ad0 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20  implements this 
37ae0 69 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c  interface by cal
37af0 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28  ling the xSleep(
37b00 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74  ).** method of t
37b10 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
37b20 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
37b30 20 20 49 66 20 74 68 65 20 78 53 6c 65 65 70 28    If the xSleep(
37b40 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74  ) method.** of t
37b50 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69  he default VFS i
37b60 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65  s not implemente
37b70 64 20 63 6f 72 72 65 63 74 6c 79 2c 20 6f 72 20  d correctly, or 
37b80 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  not implemented 
37b90 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e 20  at.** all, then 
37ba0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
37bb0 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20  sqlite3_sleep() 
37bc0 6d 61 79 20 64 65 76 69 61 74 65 20 66 72 6f 6d  may deviate from
37bd0 20 74 68 65 20 64 65 73 63 72 69 70 74 69 6f 6e   the description
37be0 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72 65 76 69  .** in the previ
37bf0 6f 75 73 20 70 61 72 61 67 72 61 70 68 73 2e 0a  ous paragraphs..
37c00 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
37c10 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  leep(int);../*.*
37c20 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
37c30 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48   Of The Folder H
37c40 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79  olding Temporary
37c50 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49   Files.**.** ^(I
37c60 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61  f this global va
37c70 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74  riable is made t
37c80 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  o point to a str
37c90 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20  ing which is.** 
37ca0 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f  the name of a fo
37cb0 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72  lder (a.k.a. dir
37cc0 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c  ectory), then al
37cd0 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  l temporary file
37ce0 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20  s.** created by 
37cf0 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e  SQLite when usin
37d00 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71  g a built-in [sq
37d10 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d  lite3_vfs | VFS]
37d20 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61 63  .** will be plac
37d30 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63  ed in that direc
37d40 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74 68 69  tory.)^  ^If thi
37d50 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73  s variable.** is
37d60 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
37d70 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72   then SQLite per
37d80 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20 66  forms a search f
37d90 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  or an appropriat
37da0 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  e.** temporary f
37db0 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ile directory..*
37dc0 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
37dd0 73 20 61 72 65 20 73 74 72 6f 6e 67 6c 79 20 64  s are strongly d
37de0 69 73 63 6f 75 72 61 67 65 64 20 66 72 6f 6d 20  iscouraged from 
37df0 75 73 69 6e 67 20 74 68 69 73 20 67 6c 6f 62 61  using this globa
37e00 6c 20 76 61 72 69 61 62 6c 65 2e 0a 2a 2a 20 49  l variable..** I
37e10 74 20 69 73 20 72 65 71 75 69 72 65 64 20 74 6f  t is required to
37e20 20 73 65 74 20 61 20 74 65 6d 70 6f 72 61 72 79   set a temporary
37e30 20 66 6f 6c 64 65 72 20 6f 6e 20 57 69 6e 64 6f   folder on Windo
37e40 77 73 20 52 75 6e 74 69 6d 65 20 28 57 69 6e 52  ws Runtime (WinR
37e50 54 29 2e 0a 2a 2a 20 42 75 74 20 66 6f 72 20 61  T)..** But for a
37e60 6c 6c 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72  ll other platfor
37e70 6d 73 2c 20 69 74 20 69 73 20 68 69 67 68 6c 79  ms, it is highly
37e80 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
37e90 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  t applications.*
37ea0 2a 20 6e 65 69 74 68 65 72 20 72 65 61 64 20 6e  * neither read n
37eb0 6f 72 20 77 72 69 74 65 20 74 68 69 73 20 76 61  or write this va
37ec0 72 69 61 62 6c 65 2e 20 20 54 68 69 73 20 67 6c  riable.  This gl
37ed0 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73  obal variable is
37ee0 20 61 20 72 65 6c 69 63 0a 2a 2a 20 74 68 61 74   a relic.** that
37ef0 20 65 78 69 73 74 73 20 66 6f 72 20 62 61 63 6b   exists for back
37f00 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
37f10 69 74 79 20 6f 66 20 6c 65 67 61 63 79 20 61 70  ity of legacy ap
37f20 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73  plications and s
37f30 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 76 6f 69  hould.** be avoi
37f40 64 65 64 20 69 6e 20 6e 65 77 20 70 72 6f 6a 65  ded in new proje
37f50 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73  cts..**.** It is
37f60 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61   not safe to rea
37f70 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  d or modify this
37f80 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72   variable in mor
37f90 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68  e than one.** th
37fa0 72 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20  read at a time. 
37fb0 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
37fc0 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66  to read or modif
37fd0 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  y this variable.
37fe0 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73  ** if a [databas
37ff0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
38000 20 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74   being used at t
38010 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20  he same time in 
38020 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68  a separate.** th
38030 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69  read..** It is i
38040 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69  ntended that thi
38050 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65  s variable be se
38060 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72  t once.** as par
38070 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69  t of process ini
38080 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20  tialization and 
38090 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74  before any SQLit
380a0 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  e interface.** r
380b0 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65  outines have bee
380c0 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61  n called and tha
380d0 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
380e0 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64  remain unchanged
380f0 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a  .** thereafter..
38100 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70  **.** ^The [temp
38110 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
38120 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64   pragma] may mod
38130 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
38140 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69  e and cause.** i
38150 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65  t to point to me
38160 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
38170 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
38180 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f  oc].  ^Furthermo
38190 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70  re,.** the [temp
381a0 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
381b0 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20   pragma] always 
381c0 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79  assumes that any
381d0 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20   string.** that 
381e0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f  this variable po
381f0 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20  ints to is held 
38200 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  in memory obtain
38210 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
38220 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64  ite3_malloc] and
38230 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20   the pragma may 
38240 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20  attempt to free 
38250 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75  that memory.** u
38260 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
38270 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69  ee]..** Hence, i
38280 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  f this variable 
38290 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65  is modified dire
382a0 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20  ctly, either it 
382b0 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64  should be.** mad
382c0 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74  e NULL or made t
382d0 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
382e0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
382f0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
38300 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20  .** or else the 
38310 75 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70  use of the [temp
38320 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
38330 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20   pragma] should 
38340 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 20 45  be avoided..** E
38350 78 63 65 70 74 20 77 68 65 6e 20 72 65 71 75 65  xcept when reque
38360 73 74 65 64 20 62 79 20 74 68 65 20 5b 74 65 6d  sted by the [tem
38370 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
38380 79 20 70 72 61 67 6d 61 5d 2c 20 53 51 4c 69 74  y pragma], SQLit
38390 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 66 72  e.** does not fr
383a0 65 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68  ee the memory th
383b0 61 74 20 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  at sqlite3_temp_
383c0 64 69 72 65 63 74 6f 72 79 20 70 6f 69 6e 74 73  directory points
383d0 20 74 6f 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20   to.  If.** the 
383e0 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 61 6e 74  application want
383f0 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 74 6f  s that memory to
38400 20 62 65 20 66 72 65 65 64 2c 20 69 74 20 6d 75   be freed, it mu
38410 73 74 20 64 6f 0a 2a 2a 20 73 6f 20 69 74 73 65  st do.** so itse
38420 6c 66 2c 20 74 61 6b 69 6e 67 20 63 61 72 65 20  lf, taking care 
38430 74 6f 20 6f 6e 6c 79 20 64 6f 20 73 6f 20 61 66  to only do so af
38440 74 65 72 20 61 6c 6c 20 5b 64 61 74 61 62 61 73  ter all [databas
38450 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
38460 20 6f 62 6a 65 63 74 73 20 68 61 76 65 20 62 65   objects have be
38470 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a  en destroyed..**
38480 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
38490 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75  indows Runtime u
384a0 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74  sers:</b>  The t
384b0 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f  emporary directo
384c0 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a  ry must be set.*
384d0 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  * prior to calli
384e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ng [sqlite3_open
384f0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ] or [sqlite3_op
38500 65 6e 5f 76 32 5d 2e 20 20 4f 74 68 65 72 77 69  en_v2].  Otherwi
38510 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66  se, various.** f
38520 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71  eatures that req
38530 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20  uire the use of 
38540 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20  temporary files 
38550 6d 61 79 20 66 61 69 6c 2e 20 20 48 65 72 65 20  may fail.  Here 
38560 69 73 20 61 6e 0a 2a 2a 20 65 78 61 6d 70 6c 65  is an.** example
38570 20 6f 66 20 68 6f 77 20 74 6f 20 64 6f 20 74 68   of how to do th
38580 69 73 20 75 73 69 6e 67 20 43 2b 2b 20 77 69 74  is using C++ wit
38590 68 20 74 68 65 20 57 69 6e 64 6f 77 73 20 52 75  h the Windows Ru
385a0 6e 74 69 6d 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  ntime:.**.** <bl
385b0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
385c0 2a 20 4c 50 43 57 53 54 52 20 7a 50 61 74 68 20  * LPCWSTR zPath 
385d0 3d 20 57 69 6e 64 6f 77 73 3a 3a 53 74 6f 72 61  = Windows::Stora
385e0 67 65 3a 3a 41 70 70 6c 69 63 61 74 69 6f 6e 44  ge::ApplicationD
385f0 61 74 61 3a 3a 43 75 72 72 65 6e 74 2d 3e 0a 2a  ata::Current->.*
38600 2a 20 26 6e 62 73 70 3b 20 20 20 20 20 54 65 6d  * &nbsp;     Tem
38610 70 6f 72 61 72 79 46 6f 6c 64 65 72 2d 3e 50 61  poraryFolder->Pa
38620 74 68 2d 3e 44 61 74 61 28 29 3b 0a 2a 2a 20 63  th->Data();.** c
38630 68 61 72 20 7a 50 61 74 68 42 75 66 26 23 39 31  har zPathBuf&#91
38640 3b 4d 41 58 5f 50 41 54 48 20 2b 20 31 26 23 39  ;MAX_PATH + 1&#9
38650 33 3b 3b 0a 2a 2a 20 6d 65 6d 73 65 74 28 7a 50  3;;.** memset(zP
38660 61 74 68 42 75 66 2c 20 30 2c 20 73 69 7a 65 6f  athBuf, 0, sizeo
38670 66 28 7a 50 61 74 68 42 75 66 29 29 3b 0a 2a 2a  f(zPathBuf));.**
38680 20 57 69 64 65 43 68 61 72 54 6f 4d 75 6c 74 69   WideCharToMulti
38690 42 79 74 65 28 43 50 5f 55 54 46 38 2c 20 30 2c  Byte(CP_UTF8, 0,
386a0 20 7a 50 61 74 68 2c 20 2d 31 2c 20 7a 50 61 74   zPath, -1, zPat
386b0 68 42 75 66 2c 20 73 69 7a 65 6f 66 28 7a 50 61  hBuf, sizeof(zPa
386c0 74 68 42 75 66 29 2c 0a 2a 2a 20 26 6e 62 73 70  thBuf),.** &nbsp
386d0 3b 20 20 20 20 20 4e 55 4c 4c 2c 20 4e 55 4c 4c  ;     NULL, NULL
386e0 29 3b 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 65  );.** sqlite3_te
386f0 6d 70 5f 64 69 72 65 63 74 6f 72 79 20 3d 20 73  mp_directory = s
38700 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
38710 25 73 22 2c 20 7a 50 61 74 68 42 75 66 29 3b 0a  %s", zPathBuf);.
38720 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
38730 71 75 6f 74 65 3e 0a 2a 2f 0a 53 51 4c 49 54 45  quote>.*/.SQLITE
38740 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71  _EXTERN char *sq
38750 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63  lite3_temp_direc
38760 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tory;../*.** CAP
38770 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54  I3REF: Name Of T
38780 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e  he Folder Holdin
38790 67 20 44 61 74 61 62 61 73 65 20 46 69 6c 65 73  g Database Files
387a0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73  .**.** ^(If this
387b0 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
387c0 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
387d0 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68  t to a string wh
387e0 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61  ich is.** the na
387f0 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28  me of a folder (
38800 61 2e 6b 2e 61 2e