/ Hex Artifact Content
Login

Artifact a0866dafaa412d1e89abbc78d2b44b12cf95d1d1:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
23f0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2400: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2410: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
2420: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2430: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
2440: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
2450: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2460: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
2470: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2480: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2490: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
24a0: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
24b0: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
24c0: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
24d0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
24e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24f0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2500: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2510: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
2520: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
2530: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
2540: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
2550: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
2560: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
2570: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2580: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2590: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
25a0: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
25b0: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
25c0: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
25d0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
25e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25f0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2600: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2610: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
2620: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
2630: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
2640: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2650: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
2660: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
2670: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2680: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2690: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26a0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26b0: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
26c0: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
26d0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
26e0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
26f0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2700: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2710: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
2720: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
2730: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2740: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
2750: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2760: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
2770: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2780: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2790: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
27a0: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
27b0: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
27c0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
27e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
27f0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2800: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2810: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
2820: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2830: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2840: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2850: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2860: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2870: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2890: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
28a0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
28b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
28c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
28d0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
28e0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2900: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2910: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2920: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2930: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2940: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2950: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2960: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2970: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2980: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2990: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
29a0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
29b0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
29c0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
29d0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
29e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
29f0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2a00: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2a10: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2a20: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
2a30: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2a40: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2a50: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
2a60: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
2a70: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
2a80: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
2a90: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
2aa0: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
2ab0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2ac0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
2ad0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ae0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2af0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2b00: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2b10: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2b20: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2b30: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2b40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2b50: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2b60: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2b70: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2b80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2b90: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2ba0: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2bb0: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2bc0: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2bd0: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2be0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2bf0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2c00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2c10: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2c20: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2c30: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2c40: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2c50: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e  ements.** and un
2c60: 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33  finished sqlite3
2c70: 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74  _backups, then t
2c80: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2c90: 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a  ection becomes.*
2ca0: 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a  * an unusable "z
2cb0: 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c  ombie" which wil
2cc0: 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2cd0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77  be deallocated w
2ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20  hen the.** last 
2cf0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d00: 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20  nt is finalized 
2d10: 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  or the last sqli
2d20: 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a  te3_backup is.**
2d30: 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20   finished.  The 
2d40: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2d50: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2d60: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
2d70: 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61   with.** host la
2d80: 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65  nguages that are
2d90: 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74   garbage collect
2da0: 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68  ed, and where th
2db0: 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68  e order in which
2dc0: 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20  .** destructors 
2dd0: 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72  are called is ar
2de0: 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41  bitrary..**.** A
2df0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
2e00: 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ld [sqlite3_fina
2e10: 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d  lize | finalize]
2e20: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73   all [prepared s
2e30: 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b  tatements],.** [
2e40: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
2e50: 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20  se | close] all 
2e60: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20  [BLOB handles], 
2e70: 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
2e80: 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c  _backup_finish |
2e90: 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71   finish] all [sq
2ea0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
2eb0: 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64  jects associated
2ec0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71  .** with the [sq
2ed0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72  lite3] object pr
2ee0: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  ior to attemptin
2ef0: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f  g to close the o
2f00: 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73  bject.  ^If.** s
2f10: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2f20: 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61  ) is called on a
2f30: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2f40: 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c  ction] that stil
2f50: 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e  l has.** outstan
2f60: 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73  ding [prepared s
2f70: 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f  tatements], [BLO
2f80: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f  B handles], and/
2f90: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  or.** [sqlite3_b
2fa0: 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74  ackup] objects t
2fb0: 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20 53  hen it returns S
2fc0: 51 4c 49 54 45 5f 4f 4b 20 62 75 74 20 74 68 65  QLITE_OK but the
2fd0: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
2fe0: 20 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73   of resources is
2ff0: 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
3000: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74  all [prepared st
3010: 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42  atements], [BLOB
3020: 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e   handles],.** an
3030: 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  d [sqlite3_backu
3040: 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61  p] objects are a
3050: 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  lso destroyed..*
3060: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c  *.** ^If an [sql
3070: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20  ite3] object is 
3080: 64 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20  destroyed while 
3090: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
30a0: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72   open,.** the tr
30b0: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74  ansaction is aut
30c0: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
30d0: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
30e0: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e C parameter to
30f0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
3100: 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  C)] and [sqlite3
3110: 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a  _close_v2(C)].**
3120: 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
3130: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
3140: 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  r or an [sqlite3
3150: 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72  ] object pointer
3160: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3170: 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  m [sqlite3_open(
3180: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
3190: 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
31a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
31b0: 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69  ], and not previ
31c0: 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a  ously closed..**
31d0: 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
31e0: 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c  3_close() or sql
31f0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
3200: 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
3210: 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ter.** argument 
3220: 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
3230: 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  -op..*/.int sqli
3240: 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  te3_close(sqlite
3250: 33 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  3*);.int sqlite3
3260: 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65  _close_v2(sqlite
3270: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  3*);../*.** The 
3280: 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62  type for a callb
3290: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ack function..**
32a0: 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20   This is legacy 
32b0: 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20  and deprecated. 
32c0: 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20   It is included 
32d0: 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a  for historical.*
32e0: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
32f0: 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d  and is not docum
3300: 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65  ented..*/.typede
3310: 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f  f int (*sqlite3_
3320: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
3330: 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72  int,char**, char
3340: 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  **);../*.** CAPI
3350: 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51  3REF: One-Step Q
3360: 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49  uery Execution I
3370: 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54  nterface.**.** T
3380: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3390: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61  ) interface is a
33a0: 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61   convenience wra
33b0: 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
33c0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
33d0: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
33e0: 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71  step()], and [sq
33f0: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
3400: 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77  ],.** that allow
3410: 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  s an application
3420: 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65   to run multiple
3430: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53   statements of S
3440: 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61  QL.** without ha
3450: 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f  ving to use a lo
3460: 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a  t of C code. .**
3470: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
3480: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
3490: 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d  e runs zero or m
34a0: 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ore UTF-8 encode
34b0: 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  d,.** semicolon-
34c0: 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 61  separate SQL sta
34d0: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69  tements passed i
34e0: 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75  nto its 2nd argu
34f0: 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20  ment,.** in the 
3500: 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b  context of the [
3510: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3520: 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61  ion] passed in a
3530: 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67  s its 1st.** arg
3540: 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20  ument.  ^If the 
3550: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
3560: 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 67  n of the 3rd arg
3570: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69  ument to.** sqli
3580: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
3590: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20  t NULL, then it 
35a0: 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65  is invoked for e
35b0: 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a  ach result row.*
35c0: 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20  * coming out of 
35d0: 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 51  the evaluated SQ
35e0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e  L statements.  ^
35f0: 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74  The 4th argument
3600: 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65   to.** sqlite3_e
3610: 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65 64  xec() is relayed
3620: 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
3630: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  1st argument of 
3640: 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  each.** callback
3650: 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49   invocation.  ^I
3660: 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70  f the callback p
3670: 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
3680: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e  3_exec().** is N
3690: 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c  ULL, then no cal
36a0: 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e  lback is ever in
36b0: 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74  voked and result
36c0: 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e   rows are.** ign
36d0: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ored..**.** ^If 
36e0: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
36f0: 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67  while evaluating
3700: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
3710: 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a  nts passed into.
3720: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3730: 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f  ), then executio
3740: 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
3750: 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73   statement stops
3760: 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65   and.** subseque
3770: 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  nt statements ar
3780: 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20  e skipped.  ^If 
3790: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
37a0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
37b0: 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  c().** is not NU
37c0: 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f  LL then any erro
37d0: 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 69  r message is wri
37e0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
37f0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3800: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
3810: 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20  c()] and passed 
3820: 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65  back through the
3830: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a   5th parameter..
3840: 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f  ** To avoid memo
3850: 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70  ry leaks, the ap
3860: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
3870: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
3880: 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65  _free()].** on e
3890: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
38a0: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74 68  ings returned th
38b0: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
38c0: 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66  rameter of.** of
38d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
38e0: 61 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20  after the error 
38f0: 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
3900: 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64  s no longer need
3910: 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35  ed..** ^If the 5
3920: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
3930: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3940: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e  s not NULL and n
3950: 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75  o errors.** occu
3960: 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  r, then sqlite3_
3970: 65 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20  exec() sets the 
3980: 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35  pointer in its 5
3990: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
39a0: 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72  ** NULL before r
39b0: 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
39c0: 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65  ^If an sqlite3_e
39d0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72  xec() callback r
39e0: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
39f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3a00: 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  c().** routine r
3a10: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42  eturns SQLITE_AB
3a20: 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f  ORT without invo
3a30: 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63  king the callbac
3a40: 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77  k again and.** w
3a50: 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61  ithout running a
3a60: 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51  ny subsequent SQ
3a70: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
3a80: 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67  .** ^The 2nd arg
3a90: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
3aa0: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
3ab0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73  back function is
3ac0: 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
3ad0: 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
3ae0: 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33   result.  ^The 3
3af0: 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rd argument to t
3b00: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3b10: 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73  ).** callback is
3b20: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3b30: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3b40: 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20   obtained as if 
3b50: 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
3b60: 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
3b70: 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f   one for each co
3b80: 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c  lumn.  ^If an el
3b90: 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65  ement of a.** re
3ba0: 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c  sult row is NULL
3bb0: 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   then the corres
3bc0: 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70  ponding string p
3bd0: 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a  ointer for the.*
3be0: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  * sqlite3_exec()
3bf0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e   callback is a N
3c00: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54  ULL pointer.  ^T
3c10: 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20  he 4th argument 
3c20: 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  to the.** sqlite
3c30: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3c40: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  k is an array of
3c50: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
3c60: 69 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a  ings where each.
3c70: 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65  ** entry represe
3c80: 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  nts the name of 
3c90: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65  corresponding re
3ca0: 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f  sult column as o
3cb0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3cc0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
3cd0: 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  name()]..**.** ^
3ce0: 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  If the 2nd param
3cf0: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
3d00: 65 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c  exec() is a NULL
3d10: 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e   pointer, a poin
3d20: 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70  ter.** to an emp
3d30: 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20  ty string, or a 
3d40: 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e  pointer that con
3d50: 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65  tains only white
3d60: 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a  space and/or .**
3d70: 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74   SQL comments, t
3d80: 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65  hen no SQL state
3d90: 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61  ments are evalua
3da0: 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61  ted and the data
3db0: 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63  base.** is not c
3dc0: 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65  hanged..**.** Re
3dd0: 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a  strictions:.**.*
3de0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
3df0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e00: 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20  ust insure that 
3e10: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
3e20: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3e30: 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61  c().**      is a
3e40: 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20   valid and open 
3e50: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3e60: 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  tion]..** <li> T
3e70: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e80: 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64  ust not close [d
3e90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3ea0: 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
3eb0: 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73 74  .**      the 1st
3ec0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3ed0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69  lite3_exec() whi
3ee0: 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  le sqlite3_exec(
3ef0: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  ) is running..**
3f00: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3f10: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d  ation must not m
3f20: 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73 74  odify the SQL st
3f30: 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73  atement text pas
3f40: 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20  sed into.**     
3f50: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
3f60: 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78  er of sqlite3_ex
3f70: 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74  ec() while sqlit
3f80: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e  e3_exec() is run
3f90: 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  ning..** </ul>.*
3fa0: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
3fb0: 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ec(.  sqlite3*, 
3fc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fe0: 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
3ff0: 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
4000: 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20  char *sql,      
4010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4020: 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
4030: 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
4040: 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29   int (*callback)
4050: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
4060: 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43  *,char**),  /* C
4070: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
4080: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20   */.  void *,   
4090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74   /* 1st argument
40c0: 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a   to callback */.
40d0: 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20    char **errmsg 
40e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
4100: 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
4110: 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  n here */.);../*
4120: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
4130: 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45  sult Codes.** KE
4140: 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f  YWORDS: SQLITE_O
4150: 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b  K {error code} {
4160: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
4170: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
4180: 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20  t code} {result 
4190: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e  codes}.**.** Man
41a0: 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f  y SQLite functio
41b0: 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74  ns return an int
41c0: 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65  eger result code
41d0: 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68   from the set sh
41e0: 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f  own.** here in o
41f0: 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65  rder to indicate
4200: 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c   success or fail
4210: 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65  ure..**.** New e
4220: 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62  rror codes may b
4230: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
4240: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
4250: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  Lite..**.** See 
4260: 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f  also: [SQLITE_IO
4270: 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e  ERR_READ | exten
4280: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4290: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  ],.** [sqlite3_v
42a0: 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28  tab_on_conflict(
42b0: 29 5d 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42  )] [SQLITE_ROLLB
42c0: 41 43 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64  ACK | result cod
42d0: 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  es]..*/.#define 
42e0: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
42f0: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
4300: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
4310: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
4320: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
4330: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
4340: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
4350: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
4360: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
4370: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4380: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
4390: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
43a0: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
43b0: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
43c0: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
43d0: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
43e0: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
43f0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
4400: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
4410: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
4420: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
4430: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
4440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4450: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
4460: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
4470: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
4480: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4490: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
44a0: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
44b0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
44c0: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
44d0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
44e0: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
44f0: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
4500: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4510: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
4520: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
4530: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
4540: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
4550: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
4560: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
4570: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
4580: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
4590: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
45a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
45b0: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
45c0: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
45d0: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
45e0: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
45f0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
4600: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
4610: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
4620: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
4630: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4640: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
4650: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20  12   /* Unknown 
4660: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65  opcode in sqlite
4670: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
4680: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4690: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
46a0: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
46b0: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
46c0: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
46d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
46e0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
46f0: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
4700: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
4710: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4720: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
4730: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61  OL    15   /* Da
4740: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74  tabase lock prot
4750: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64  ocol error */.#d
4760: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50  efine SQLITE_EMP
4770: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a  TY       16   /*
4780: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70   Database is emp
4790: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ty */.#define SQ
47a0: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20  LITE_SCHEMA     
47b0: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74   17   /* The dat
47c0: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
47d0: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nged */.#define 
47e0: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20  SQLITE_TOOBIG   
47f0: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e     18   /* Strin
4800: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64  g or BLOB exceed
4810: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a  s size limit */.
4820: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
4830: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
4840: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
4850: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
4860: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tion */.#define 
4870: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20  SQLITE_MISMATCH 
4880: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20     20   /* Data 
4890: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f  type mismatch */
48a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
48b0: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20  MISUSE      21  
48c0: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64   /* Library used
48d0: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a   incorrectly */.
48e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
48f0: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20  OLFS       22   
4900: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75  /* Uses OS featu
4910: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  res not supporte
4920: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65  d on host */.#de
4930: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
4940: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
4950: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65  Authorization de
4960: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4970: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20  SQLITE_FORMAT   
4980: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c     24   /* Auxil
4990: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f  iary database fo
49a0: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64  rmat error */.#d
49b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e  efine SQLITE_RAN
49c0: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a  GE       25   /*
49d0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
49e0: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f  o sqlite3_bind o
49f0: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23  ut of range */.#
4a00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4a10: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f  TADB      26   /
4a20: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68  * File opened th
4a30: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  at is not a data
4a40: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4a50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20  fine SQLITE_ROW 
4a60: 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20          100  /* 
4a70: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
4a80: 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72  as another row r
4a90: 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  eady */.#define 
4aa0: 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20  SQLITE_DONE     
4ab0: 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74     101  /* sqlit
4ac0: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69  e3_step() has fi
4ad0: 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
4ae0: 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72   */./* end-of-er
4af0: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a  ror-codes */../*
4b00: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78  .** CAPI3REF: Ex
4b10: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
4b20: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
4b30: 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   {extended error
4b40: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64   code} {extended
4b50: 20 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a   error codes}.**
4b60: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
4b70: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4b80: 7d 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75  } {extended resu
4b90: 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20  lt codes}.**.** 
4ba0: 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63  In its default c
4bb0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51  onfiguration, SQ
4bc0: 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65  Lite API routine
4bd0: 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  s return one of 
4be0: 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53  26 integer.** [S
4bf0: 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c  QLITE_OK | resul
4c00: 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76  t codes].  Howev
4c10: 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68  er, experience h
4c20: 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61  as shown that ma
4c30: 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72  ny of.** these r
4c40: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
4c50: 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e  too coarse-grain
4c60: 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74  ed.  They do not
4c70: 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d   provide as.** m
4c80: 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  uch information 
4c90: 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61  about problems a
4ca0: 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69  s programmers mi
4cb0: 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e  ght like.  In an
4cc0: 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64   effort to.** ad
4cd0: 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65  dress this, newe
4ce0: 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
4cf0: 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e  Lite (version 3.
4d00: 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69  3.8 and later) i
4d10: 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72  nclude.** suppor
4d20: 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  t for additional
4d30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68   result codes th
4d40: 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20  at provide more 
4d50: 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61  detailed informa
4d60: 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72  tion.** about er
4d70: 72 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64  rors. The extend
4d80: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
4d90: 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64  are enabled or d
4da0: 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20  isabled.** on a 
4db0: 70 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e  per database con
4dc0: 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73  nection basis us
4dd0: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
4de0: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
4df0: 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49  ult_codes()] API
4e00: 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20  ..**.** Some of 
4e10: 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78  the available ex
4e20: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4e30: 64 65 73 20 61 72 65 20 6c 69 73 74 65 64 20 68  des are listed h
4e40: 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20  ere..** One may 
4e50: 65 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65  expect the numbe
4e60: 72 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65  r of extended re
4e70: 73 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20  sult codes will 
4e80: 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65  be expand.** ove
4e90: 72 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72  r time.  Softwar
4ea0: 65 20 74 68 61 74 20 75 73 65 73 20 65 78 74 65  e that uses exte
4eb0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4ec0: 73 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a  s should expect.
4ed0: 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65  ** to see new re
4ee0: 73 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75  sult codes in fu
4ef0: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
4f00: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
4f10: 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73  he SQLITE_OK res
4f20: 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65  ult code will ne
4f30: 76 65 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e  ver be extended.
4f40: 20 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73    It will always
4f50: 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a  .** be exactly z
4f60: 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ero..*/.#define 
4f70: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
4f80: 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  D              (
4f90: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4fa0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
4fb0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
4fc0: 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53  T_READ        (S
4fd0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
4fe0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4ff0: 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45  LITE_IOERR_WRITE
5000: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5010: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c  LITE_IOERR | (3<
5020: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5030: 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20  ITE_IOERR_FSYNC 
5040: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5050: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c  ITE_IOERR | (4<<
5060: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5070: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59  TE_IOERR_DIR_FSY
5080: 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  NC         (SQLI
5090: 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38  TE_IOERR | (5<<8
50a0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
50b0: 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45  E_IOERR_TRUNCATE
50c0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
50d0: 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29  E_IOERR | (6<<8)
50e0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
50f0: 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20  _IOERR_FSTAT    
5100: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5110: 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29  _IOERR | (7<<8))
5120: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5130: 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20  IOERR_UNLOCK    
5140: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5150: 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a  IOERR | (8<<8)).
5160: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5170: 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20  OERR_RDLOCK     
5180: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5190: 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23  OERR | (9<<8)).#
51a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51b0: 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ERR_DELETE      
51c0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
51d0: 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23  ERR | (10<<8)).#
51e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51f0: 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20  ERR_BLOCKED     
5200: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5210: 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23  ERR | (11<<8)).#
5220: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5230: 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ERR_NOMEM       
5240: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5250: 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23  ERR | (12<<8)).#
5260: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5270: 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20  ERR_ACCESS      
5280: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5290: 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23  ERR | (13<<8)).#
52a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
52b0: 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45  ERR_CHECKRESERVE
52c0: 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f  DLOCK (SQLITE_IO
52d0: 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23  ERR | (14<<8)).#
52e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
52f0: 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20  ERR_LOCK        
5300: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5310: 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23  ERR | (15<<8)).#
5320: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5330: 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20  ERR_CLOSE       
5340: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5350: 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23  ERR | (16<<8)).#
5360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5370: 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20  ERR_DIR_CLOSE   
5380: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5390: 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23  ERR | (17<<8)).#
53a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
53b0: 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20  ERR_SHMOPEN     
53c0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
53d0: 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23  ERR | (18<<8)).#
53e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
53f0: 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20  ERR_SHMSIZE     
5400: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5410: 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23  ERR | (19<<8)).#
5420: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5430: 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20  ERR_SHMLOCK     
5440: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5450: 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23  ERR | (20<<8)).#
5460: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5470: 45 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20  ERR_SHMMAP      
5480: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5490: 45 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23  ERR | (21<<8)).#
54a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
54b0: 45 52 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20  ERR_SEEK        
54c0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
54d0: 45 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23  ERR | (22<<8)).#
54e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
54f0: 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54  ERR_DELETE_NOENT
5500: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5510: 45 52 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23  ERR | (23<<8)).#
5520: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5530: 45 52 52 5f 4d 4d 41 50 20 20 20 20 20 20 20 20  ERR_MMAP        
5540: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5550: 45 52 52 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23  ERR | (24<<8)).#
5560: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
5570: 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45  CKED_SHAREDCACHE
5580: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f        (SQLITE_LO
5590: 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a  CKED |  (1<<8)).
55a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
55b0: 55 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20  USY_RECOVERY    
55c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42         (SQLITE_B
55d0: 55 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29  USY   |  (1<<8))
55e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55f0: 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44  CANTOPEN_NOTEMPD
5600: 49 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  IR      (SQLITE_
5610: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38  CANTOPEN | (1<<8
5620: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5630: 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52  E_CANTOPEN_ISDIR
5640: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5650: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c  E_CANTOPEN | (2<
5660: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5670: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c  ITE_CANTOPEN_FUL
5680: 4c 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  LPATH       (SQL
5690: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
56a0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
56b0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
56c0: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
56d0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
56e0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
56f0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5700: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
5710: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5720: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5730: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5740: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
5750: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5760: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
5770: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5780: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  NLY_ROLLBACK    
5790: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
57a0: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  NLY | (3<<8)).#d
57b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f  efine SQLITE_ABO
57c0: 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20  RT_ROLLBACK     
57d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f       (SQLITE_ABO
57e0: 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  RT | (2<<8)).#de
57f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5800: 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 20  TRAINT_CHECK    
5810: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5820: 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29  TRAINT | (1<<8))
5830: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5840: 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49  CONSTRAINT_COMMI
5850: 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f  THOOK   (SQLITE_
5860: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 3c  CONSTRAINT | (2<
5870: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5880: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46  ITE_CONSTRAINT_F
5890: 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51 4c  OREIGNKEY   (SQL
58a0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
58b0: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
58c0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
58d0: 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  NT_FUNCTION     
58e0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
58f0: 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  NT | (4<<8)).#de
5900: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5910: 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20  TRAINT_NOTNULL  
5920: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5930: 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29  TRAINT | (5<<8))
5940: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5950: 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d 41  CONSTRAINT_PRIMA
5960: 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f  RYKEY   (SQLITE_
5970: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 3c  CONSTRAINT | (6<
5980: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5990: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54  ITE_CONSTRAINT_T
59a0: 52 49 47 47 45 52 20 20 20 20 20 20 28 53 51 4c  RIGGER      (SQL
59b0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
59c0: 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (7<<8)).#define
59d0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
59e0: 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20  NT_UNIQUE       
59f0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5a00: 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  NT | (8<<8)).#de
5a10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5a20: 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20 20  TRAINT_VTAB     
5a30: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5a40: 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29  TRAINT | (9<<8))
5a50: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5a60: 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65  : Flags For File
5a70: 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73   Open Operations
5a80: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74  .**.** These bit
5a90: 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65   values are inte
5aa0: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
5ab0: 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d  the.** 3rd param
5ac0: 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  eter to the [sql
5ad0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
5ae0: 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a  interface and.**
5af0: 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 61   in the 4th para
5b00: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5b10: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
5b20: 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66   method..*/.#def
5b30: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5b40: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20  READONLY        
5b50: 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20   0x00000001  /* 
5b60: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5b70: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5b80: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5b90: 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20  READWRITE       
5ba0: 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20   0x00000002  /* 
5bb0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5bc0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5bd0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5be0: 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20  CREATE          
5bf0: 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20   0x00000004  /* 
5c00: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5c10: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5c20: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5c30: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20  DELETEONCLOSE   
5c40: 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20   0x00000008  /* 
5c50: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5c60: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5c70: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20  EXCLUSIVE       
5c80: 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20   0x00000010  /* 
5c90: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5ca0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5cb0: 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20  AUTOPROXY       
5cc0: 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20   0x00000020  /* 
5cd0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5ce0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5cf0: 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20 20  URI             
5d00: 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a 20   0x00000040  /* 
5d10: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5d20: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5d30: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5d40: 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20 20  MEMORY          
5d50: 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a 20   0x00000080  /* 
5d60: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5d70: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5d80: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5d90: 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20  MAIN_DB         
5da0: 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20   0x00000100  /* 
5db0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5dc0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5dd0: 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20  TEMP_DB         
5de0: 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20   0x00000200  /* 
5df0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5e00: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5e10: 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20  TRANSIENT_DB    
5e20: 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20   0x00000400  /* 
5e30: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5e40: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5e50: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  MAIN_JOURNAL    
5e60: 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20   0x00000800  /* 
5e70: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5e80: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5e90: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  TEMP_JOURNAL    
5ea0: 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20   0x00001000  /* 
5eb0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5ec0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5ed0: 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20  SUBJOURNAL      
5ee0: 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20   0x00002000  /* 
5ef0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5f00: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5f10: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20  MASTER_JOURNAL  
5f20: 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20   0x00004000  /* 
5f30: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5f40: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5f50: 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20  NOMUTEX         
5f60: 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20   0x00008000  /* 
5f70: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5f80: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5f90: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5fa0: 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20  FULLMUTEX       
5fb0: 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20   0x00010000  /* 
5fc0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5fd0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5fe0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5ff0: 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20  SHAREDCACHE     
6000: 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20   0x00020000  /* 
6010: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
6020: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
6030: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6040: 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20  PRIVATECACHE    
6050: 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20   0x00040000  /* 
6060: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
6070: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
6080: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
6090: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20  WAL             
60a0: 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a 20   0x00080000  /* 
60b0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20  VFS only */../* 
60c0: 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20 20  Reserved:       
60d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
60e0: 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f 0a    0x00F00000 */.
60f0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6100: 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65   Device Characte
6110: 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68  ristics.**.** Th
6120: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
6130: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 20  eristics method 
6140: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
6150: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f  io_methods].** o
6160: 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e  bject returns an
6170: 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
6180: 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68  s a vector of th
6190: 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65  ese.** bit value
61a0: 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f  s expressing I/O
61b0: 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73   characteristics
61c0: 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f   of the mass sto
61d0: 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74  rage.** device t
61e0: 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69  hat holds the fi
61f0: 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  le that the [sql
6200: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6210: 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a  .** refers to..*
6220: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
6230: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
6240: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6250: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
6260: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
6270: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
6280: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
6290: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
62a0: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
62b0: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
62c0: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
62d0: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
62e0: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
62f0: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
6300: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
6310: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
6320: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
6330: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
6340: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
6350: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
6360: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
6370: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
6380: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
6390: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
63a0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
63b0: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
63c0: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
63d0: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
63e0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
63f0: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
6400: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
6410: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
6420: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
6430: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
6440: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
6450: 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54 68 65  o xWrite().  The
6460: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f   SQLITE_IOCAP_PO
6470: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
6480: 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  E property means
6490: 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20 72   that.** after r
64a0: 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20  eboot following 
64b0: 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65 72  a crash or power
64c0: 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20   loss, the only 
64d0: 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69  bytes in a.** fi
64e0: 6c 65 20 74 68 61 74 20 77 65 72 65 20 77 72 69  le that were wri
64f0: 74 74 65 6e 20 61 74 20 74 68 65 20 61 70 70 6c  tten at the appl
6500: 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69  ication level mi
6510: 67 68 74 20 68 61 76 65 20 63 68 61 6e 67 65 64  ght have changed
6520: 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64 6a  .** and that adj
6530: 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76 65  acent bytes, eve
6540: 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e 20 74  n bytes within t
6550: 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20 61  he same sector a
6560: 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 64  re.** guaranteed
6570: 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65 64   to be unchanged
6580: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
6590: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
65a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
65b0: 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66   0x00000001.#def
65c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
65d0: 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20  _ATOMIC512      
65e0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
65f0: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
6600: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
6610: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6620: 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e  x00000004.#defin
6630: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6640: 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20  TOMIC2K         
6650: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38        0x00000008
6660: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6670: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20  IOCAP_ATOMIC4K  
6680: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6690: 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20  0000010.#define 
66a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
66b0: 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20  MIC8K           
66c0: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23      0x00000020.#
66d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
66e0: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20  CAP_ATOMIC16K   
66f0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6700: 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51  00040.#define SQ
6710: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6720: 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20  C32K            
6730: 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65    0x00000080.#de
6740: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6750: 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20  P_ATOMIC64K     
6760: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6770: 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  100.#define SQLI
6780: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
6790: 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20  PEND            
67a0: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69  0x00000200.#defi
67b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
67c0: 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20  SEQUENTIAL      
67d0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30         0x0000040
67e0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
67f0: 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42  _IOCAP_UNDELETAB
6800: 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78  LE_WHEN_OPEN  0x
6810: 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65  00000800.#define
6820: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f   SQLITE_IOCAP_PO
6830: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
6840: 45 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a  E    0x00001000.
6850: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6860: 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65   File Locking Le
6870: 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  vels.**.** SQLit
6880: 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68  e uses one of th
6890: 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ese integer valu
68a0: 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  es as the second
68b0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
68c0: 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74  calls it makes t
68d0: 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e  o the xLock() an
68e0: 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68  d xUnlock() meth
68f0: 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71  ods.** of an [sq
6900: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6910: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65  ] object..*/.#de
6920: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6930: 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30  _NONE          0
6940: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6950: 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20  LOCK_SHARED     
6960: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
6970: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
6980: 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65  D      2.#define
6990: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e   SQLITE_LOCK_PEN
69a0: 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65  DING       3.#de
69b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
69c0: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 34  _EXCLUSIVE     4
69d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
69e0: 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f  : Synchronizatio
69f0: 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a  n Type Flags.**.
6a00: 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69  ** When SQLite i
6a10: 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63  nvokes the xSync
6a20: 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a  () method of an.
6a30: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
6a40: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69  ethods] object i
6a50: 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61  t uses a combina
6a60: 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65  tion of.** these
6a70: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6a80: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
6a90: 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68  gument..**.** Wh
6aa0: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59  en the SQLITE_SY
6ab0: 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67  NC_DATAONLY flag
6ac0: 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61   is used, it mea
6ad0: 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73  ns that the.** s
6ae0: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e  ync operation on
6af0: 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73  ly needs to flus
6b00: 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73  h data to mass s
6b10: 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a  torage.  Inode.*
6b20: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65  * information ne
6b30: 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65  ed not be flushe
6b40: 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20  d. If the lower 
6b50: 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68 65  four bits of the
6b60: 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53   flag.** equal S
6b70: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
6b80: 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f  L, that means to
6b90: 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   use normal fsyn
6ba0: 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a  c() semantics..*
6bb0: 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66  * If the lower f
6bc0: 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c 20 53  our bits equal S
6bd0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c  QLITE_SYNC_FULL,
6be0: 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74   that means.** t
6bf0: 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73  o use Mac OS X s
6c00: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e  tyle fullsync in
6c10: 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29  stead of fsync()
6c20: 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63  ..**.** Do not c
6c30: 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49 54  onfuse the SQLIT
6c40: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
6c50: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
6c60: 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68  LL flags.** with
6c70: 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e   the [PRAGMA syn
6c80: 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c  chronous]=NORMAL
6c90: 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e   and [PRAGMA syn
6ca0: 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a  chronous]=FULL.*
6cb0: 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65  * settings.  The
6cc0: 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72   [synchronous pr
6cd0: 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73  agma] determines
6ce0: 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74   when calls to t
6cf0: 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20  he.** xSync VFS 
6d00: 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64  method occur and
6d10: 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d   applies uniform
6d20: 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c  ly across all pl
6d30: 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20  atforms..** The 
6d40: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
6d50: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
6d60: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65  NC_FULL flags de
6d70: 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65  termine how.** e
6d80: 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f  nergetic or rigo
6d90: 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c  rous or forceful
6da0: 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74   the sync operat
6db0: 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20  ions are and.** 
6dc0: 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66  only make a diff
6dd0: 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53  erence on Mac OS
6de0: 58 20 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c  X for the defaul
6df0: 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a  t SQLite code..*
6e00: 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79 20 56  * (Third-party V
6e10: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
6e20: 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61  ns might also ma
6e30: 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69  ke the distincti
6e40: 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51  on.** between SQ
6e50: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
6e60: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
6e70: 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67  _FULL, but among
6e80: 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e   the.** operatin
6e90: 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65  g systems native
6ea0: 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  ly supported by 
6eb0: 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63  SQLite, only Mac
6ec0: 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62   OSX.** cares ab
6ed0: 6f 75 74 20 74 68 65 20 64 69 66 66 65 72 65 6e  out the differen
6ee0: 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ce.).*/.#define 
6ef0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
6f00: 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30  AL        0x0000
6f10: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
6f20: 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20  _SYNC_FULL      
6f30: 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66      0x00003.#def
6f40: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
6f50: 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78  DATAONLY      0x
6f60: 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00010../*.** CAP
6f70: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
6f80: 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61  ace Open File Ha
6f90: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73  ndle.**.** An [s
6fa0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6fb0: 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
6fc0: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74  n open file in t
6fd0: 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
6fe0: 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61  vfs | OS interfa
6ff0: 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69  ce layer].  Indi
7000: 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66  vidual OS interf
7010: 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ace.** implement
7020: 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77  ations will.** w
7030: 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20  ant to subclass 
7040: 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61  this object by a
7050: 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f  ppending additio
7060: 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f  nal fields.** fo
7070: 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e  r their own use.
7080: 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65    The pMethods e
7090: 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65  ntry is a pointe
70a0: 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  r to an.** [sqli
70b0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
70c0: 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
70d0: 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20  nes methods for 
70e0: 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f  performing.** I/
70f0: 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20  O operations on 
7100: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a  the open file..*
7110: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
7120: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71   sqlite3_file sq
7130: 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75  lite3_file;.stru
7140: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ct sqlite3_file 
7150: 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74  {.  const struct
7160: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
7170: 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20  ods *pMethods;  
7180: 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61  /* Methods for a
7190: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d  n open file */.}
71a0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
71b0: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
71c0: 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74  File Virtual Met
71d0: 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  hods Object.**.*
71e0: 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65  * Every file ope
71f0: 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ned by the [sqli
7200: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d  te3_vfs.xOpen] m
7210: 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20  ethod populates 
7220: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  an.** [sqlite3_f
7230: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c  ile] object (or,
7240: 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20   more commonly, 
7250: 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68  a subclass of th
7260: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  e.** [sqlite3_fi
7270: 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68  le] object) with
7280: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
7290: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
72a0: 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69  s object..** Thi
72b0: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
72c0: 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65   the methods use
72d0: 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  d to perform var
72e0: 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a  ious operations.
72f0: 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f  ** against the o
7300: 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65  pen file represe
7310: 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  nted by the [sql
7320: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
7330: 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  t..**.** If the 
7340: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7350: 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20  en] method sets 
7360: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
7370: 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e  .pMethods elemen
7380: 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e  t .** to a non-N
7390: 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
73a0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f  n the sqlite3_io
73b0: 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20  _methods.xClose 
73c0: 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65  method.** may be
73d0: 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66   invoked even if
73e0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
73f0: 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65  s.xOpen] reporte
7400: 64 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64  d that it failed
7410: 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77  .  The.** only w
7420: 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ay to prevent a 
7430: 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66  call to xClose f
7440: 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65  ollowing a faile
7450: 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  d [sqlite3_vfs.x
7460: 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20  Open].** is for 
7470: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7480: 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74  .xOpen] to set t
7490: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
74a0: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
74b0: 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a  .** to NULL..**.
74c0: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
74d0: 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d  ument to xSync m
74e0: 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51  ay be one of [SQ
74f0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7500: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
7510: 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65  SYNC_FULL].  The
7520: 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73   first choice is
7530: 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   the normal fsyn
7540: 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  c()..** The seco
7550: 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d  nd choice is a M
7560: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
7570: 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51  llsync.  The [SQ
7580: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
7590: 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20  LY].** flag may 
75a0: 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e  be ORed in to in
75b0: 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79  dicate that only
75c0: 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65   the data of the
75d0: 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74   file.** and not
75e0: 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73   its inode needs
75f0: 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a   to be synced..*
7600: 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72  *.** The integer
7610: 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b   values to xLock
7620: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
7630: 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c   are one of.** <
7640: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
7650: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a  ITE_LOCK_NONE],.
7660: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7670: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
7680: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7690: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a  CK_RESERVED],.**
76a0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
76b0: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a  CK_PENDING], or.
76c0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
76d0: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e  LOCK_EXCLUSIVE].
76e0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f  .** </ul>.** xLo
76f0: 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74  ck() increases t
7700: 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b  he lock. xUnlock
7710: 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65  () decreases the
7720: 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43   lock..** The xC
7730: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b  heckReservedLock
7740: 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73  () method checks
7750: 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74   whether any dat
7760: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
7770: 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74  ,.** either in t
7780: 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69  his process or i
7790: 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f  n some other pro
77a0: 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67  cess, is holding
77b0: 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20   a RESERVED,.** 
77c0: 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c  PENDING, or EXCL
77d0: 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68  USIVE lock on th
77e0: 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75  e file.  It retu
77f0: 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73  rns true.** if s
7800: 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74  uch a lock exist
7810: 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65  s and false othe
7820: 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rwise..**.** The
7830: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20   xFileControl() 
7840: 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65  method is a gene
7850: 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68  ric interface th
7860: 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d  at allows custom
7870: 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  .** VFS implemen
7880: 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63  tations to direc
7890: 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f  tly control an o
78a0: 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74  pen file using t
78b0: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
78c0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69  ile_control()] i
78d0: 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73  nterface.  The s
78e0: 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d  econd "op" argum
78f0: 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74  ent is an.** int
7900: 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68  eger opcode.  Th
7910: 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
7920: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f   is a generic po
7930: 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74  inter intended t
7940: 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20  o.** point to a 
7950: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d  structure that m
7960: 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d  ay contain argum
7970: 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e  ents or space in
7980: 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69   which to.** wri
7990: 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73  te return values
79a0: 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65  .  Potential use
79b0: 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72  s for xFileContr
79c0: 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a  ol() might be.**
79d0: 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e   functions to en
79e0: 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f  able blocking lo
79f0: 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74  cks with timeout
7a00: 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  s, to change the
7a10: 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61  .** locking stra
7a20: 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c  tegy (for exampl
7a30: 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c  e to use dot-fil
7a40: 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71  e locks), to inq
7a50: 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68  uire.** about th
7a60: 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f  e status of a lo
7a70: 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20  ck, or to break 
7a80: 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68  stale locks.  Th
7a90: 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65  e SQLite.** core
7aa0: 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70   reserves all op
7ab0: 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20  codes less than 
7ac0: 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20  100 for its own 
7ad0: 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54  use..** A [SQLIT
7ae0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
7af0: 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f  E | list of opco
7b00: 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31  des] less than 1
7b10: 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e  00 is available.
7b20: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
7b30: 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63   that define a c
7b40: 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72  ustom xFileContr
7b50: 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64  ol method should
7b60: 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20   use opcodes.** 
7b70: 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30  greater than 100
7b80: 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69   to avoid confli
7b90: 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d  cts.  VFS implem
7ba0: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
7bb0: 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
7bc0: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72  TE_NOTFOUND] for
7bd0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70   file control op
7be0: 63 6f 64 65 73 20 74 68 61 74 20 74 68 65 79 20  codes that they 
7bf0: 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e  do not.** recogn
7c00: 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ize..**.** The x
7c10: 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74  SectorSize() met
7c20: 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20  hod returns the 
7c30: 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74  sector size of t
7c40: 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61  he.** device tha
7c50: 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20  t underlies the 
7c60: 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f  file.  The secto
7c70: 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a  r size is the.**
7c80: 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74   minimum write t
7c90: 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f  hat can be perfo
7ca0: 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73  rmed without dis
7cb0: 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  turbing.** other
7cc0: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69   bytes in the fi
7cd0: 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65  le.  The xDevice
7ce0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28  Characteristics(
7cf0: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
7d00: 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72  rns a bit vector
7d10: 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61   describing beha
7d20: 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20  viors of the.** 
7d30: 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63  underlying devic
7d40: 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e:.**.** <ul>.**
7d50: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
7d60: 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c  CAP_ATOMIC].** <
7d70: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7d80: 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20  P_ATOMIC512].** 
7d90: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7da0: 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20  AP_ATOMIC1K].** 
7db0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7dc0: 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20  AP_ATOMIC2K].** 
7dd0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7de0: 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20  AP_ATOMIC4K].** 
7df0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7e00: 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20  AP_ATOMIC8K].** 
7e10: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7e20: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a  AP_ATOMIC16K].**
7e30: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
7e40: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a  CAP_ATOMIC32K].*
7e50: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
7e60: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a  OCAP_ATOMIC64K].
7e70: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7e80: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
7e90: 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  D].** <li> [SQLI
7ea0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
7eb0: 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IAL].** </ul>.**
7ec0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49  .** The SQLITE_I
7ed0: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70  OCAP_ATOMIC prop
7ee0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20  erty means that 
7ef0: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a  all writes of.**
7f00: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74   any size are at
7f10: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
7f20: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e  E_IOCAP_ATOMICnn
7f30: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e  n values.** mean
7f40: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20   that writes of 
7f50: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20  blocks that are 
7f60: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  nnn bytes in siz
7f70: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69  e and.** are ali
7f80: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65  gned to an addre
7f90: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69  ss which is an i
7fa0: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  nteger multiple 
7fb0: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74  of.** nnn are at
7fc0: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
7fd0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
7fe0: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a  END value means.
7ff0: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74  ** that when dat
8000: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f  a is appended to
8010: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74   a file, the dat
8020: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a  a is appended.**
8030: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20   first then the 
8040: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65  size of the file
8050: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65   is extended, ne
8060: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  ver the other.**
8070: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68   way around.  Th
8080: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
8090: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72  EQUENTIAL proper
80a0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
80b0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
80c0: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20  written to disk 
80d0: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65  in the same orde
80e0: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  r as calls.** to
80f0: 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a   xWrite()..**.**
8100: 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75   If xRead() retu
8110: 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  rns SQLITE_IOERR
8120: 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d  _SHORT_READ it m
8130: 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a  ust also fill.**
8140: 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70   in the unread p
8150: 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62  ortions of the b
8160: 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73  uffer with zeros
8170: 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a  .  A VFS that.**
8180: 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66   fails to zero-f
8190: 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20  ill short reads 
81a0: 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f  might seem to wo
81b0: 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  rk.  However,.**
81c0: 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f   failure to zero
81d0: 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64  -fill short read
81e0: 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c  s will eventuall
81f0: 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74  y lead to.** dat
8200: 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e  abase corruption
8210: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
8220: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
8230: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69  ethods sqlite3_i
8240: 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  o_methods;.struc
8250: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
8260: 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  hods {.  int iVe
8270: 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78  rsion;.  int (*x
8280: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66  Close)(sqlite3_f
8290: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
82a0: 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69  Read)(sqlite3_fi
82b0: 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20  le*, void*, int 
82c0: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
82d0: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
82e0: 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69  t (*xWrite)(sqli
82f0: 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74  te3_file*, const
8300: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
8310: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8320: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
8330: 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74  xTruncate)(sqlit
8340: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
8350: 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20  3_int64 size);. 
8360: 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71   int (*xSync)(sq
8370: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8380: 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28   flags);.  int (
8390: 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69  *xFileSize)(sqli
83a0: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
83b0: 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29  e3_int64 *pSize)
83c0: 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29  ;.  int (*xLock)
83d0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
83e0: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  int);.  int (*xU
83f0: 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  nlock)(sqlite3_f
8400: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
8410: 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76  t (*xCheckReserv
8420: 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  edLock)(sqlite3_
8430: 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73  file*, int *pRes
8440: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
8450: 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69  ileControl)(sqli
8460: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
8470: 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a  p, void *pArg);.
8480: 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53    int (*xSectorS
8490: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
84a0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  e*);.  int (*xDe
84b0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
84c0: 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ics)(sqlite3_fil
84d0: 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  e*);.  /* Method
84e0: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
84f0: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20  d for version 1 
8500: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d  */.  int (*xShmM
8510: 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ap)(sqlite3_file
8520: 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20  *, int iPg, int 
8530: 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20  pgsz, int, void 
8540: 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69  volatile**);.  i
8550: 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73  nt (*xShmLock)(s
8560: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8570: 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c  t offset, int n,
8580: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76   int flags);.  v
8590: 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65  oid (*xShmBarrie
85a0: 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  r)(sqlite3_file*
85b0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55  );.  int (*xShmU
85c0: 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69  nmap)(sqlite3_fi
85d0: 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46  le*, int deleteF
85e0: 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f  lag);.  /* Metho
85f0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
8600: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32  id for version 2
8610: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65 74   */.  int (*xFet
8620: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ch)(sqlite3_file
8630: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
8640: 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d 74   iOfst, int iAmt
8650: 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20  , void **pp);.  
8660: 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29 28  int (*xUnfetch)(
8670: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76  sqlite3_file*, v
8680: 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65  oid *p);.  /* Me
8690: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
86a0: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
86b0: 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69  n 3 */.  /* Addi
86c0: 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d  tional methods m
86d0: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
86e0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a  uture releases *
86f0: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
8700: 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46  3REF: Standard F
8710: 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f  ile Control Opco
8720: 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  des.**.** These 
8730: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
8740: 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f  s are opcodes fo
8750: 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  r the xFileContr
8760: 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20  ol method.** of 
8770: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
8780: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
8790: 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c  and for the [sql
87a0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
87b0: 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  l()].** interfac
87c0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  e..**.** The [SQ
87d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
87e0: 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  TATE] opcode is 
87f0: 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69  used for debuggi
8800: 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63  ng.  This.** opc
8810: 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78  ode causes the x
8820: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
8830: 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20  od to write the 
8840: 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66  current state of
8850: 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e  .** the lock (on
8860: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  e of [SQLITE_LOC
8870: 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  K_NONE], [SQLITE
8880: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a  _LOCK_SHARED],.*
8890: 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  * [SQLITE_LOCK_R
88a0: 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54  ESERVED], [SQLIT
88b0: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
88c0: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b   or [SQLITE_LOCK
88d0: 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20  _EXCLUSIVE]).** 
88e0: 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  into an integer 
88f0: 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72  that the pArg ar
8900: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f  gument points to
8910: 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74  . This capabilit
8920: 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72  y.** is used dur
8930: 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20  ing testing and 
8940: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65  only needs to be
8950: 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20   supported when 
8960: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69  SQLITE_TEST.** i
8970: 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75  s defined..** <u
8980: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  l>.** <li>[[SQLI
8990: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
89a0: 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  NT]].** The [SQL
89b0: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
89c0: 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  INT] opcode is u
89d0: 73 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f  sed by SQLite to
89e0: 20 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a   give the VFS.**
89f0: 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66   layer a hint of
8a00: 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64   how large the d
8a10: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c  atabase file wil
8a20: 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72  l grow to be dur
8a30: 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65  ing the.** curre
8a40: 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20  nt transaction. 
8a50: 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f   This hint is no
8a60: 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20  t guaranteed to 
8a70: 62 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20  be accurate but 
8a80: 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63  it.** is often c
8a90: 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72  lose.  The under
8aa0: 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20  lying VFS might 
8ab0: 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c  choose to preall
8ac0: 6f 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a  ocate database.*
8ad0: 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73  * file space bas
8ae0: 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20  ed on this hint 
8af0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70  in order to help
8b00: 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64   writes to the d
8b10: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
8b20: 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a  run faster..**.*
8b30: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
8b40: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d  CNTL_CHUNK_SIZE]
8b50: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
8b60: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
8b70: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
8b80: 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61  d to request tha
8b90: 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74  t the VFS.** ext
8ba0: 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74  ends and truncat
8bb0: 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
8bc0: 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f  file in chunks o
8bd0: 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69  f a size specifi
8be0: 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65  ed.** by the use
8bf0: 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72  r. The fourth ar
8c00: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
8c10: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
8c20: 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f  )] should .** po
8c30: 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  int to an intege
8c40: 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e  r (type int) con
8c50: 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20  taining the new 
8c60: 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73  chunk-size to us
8c70: 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d  e.** for the nom
8c80: 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e  inated database.
8c90: 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61   Allocating data
8ca0: 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20  base file space 
8cb0: 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e  in large.** chun
8cc0: 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61  ks (say 1MB at a
8cd0: 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75   time), may redu
8ce0: 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66  ce file-system f
8cf0: 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64  ragmentation and
8d00: 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66  .** improve perf
8d10: 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20  ormance on some 
8d20: 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c  systems..**.** <
8d30: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
8d40: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d  L_FILE_POINTER]]
8d50: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8d60: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
8d70: 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  ER] opcode is us
8d80: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70  ed to obtain a p
8d90: 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
8da0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
8db0: 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65  object associate
8dc0: 64 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  d with a particu
8dd0: 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  lar database.** 
8de0: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65  connection.  See
8df0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
8e00: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f  le_control()] do
8e10: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  cumentation for.
8e20: 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** additional in
8e30: 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
8e40: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
8e50: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
8e60: 5d 5d 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  ]].** ^(The [SQL
8e70: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
8e80: 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65 20 69  MITTED] opcode i
8e90: 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65  s generated inte
8ea0: 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 51 4c  rnally by.** SQL
8eb0: 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74 6f 20  ite and sent to 
8ec0: 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70 6c 61  all VFSes in pla
8ed0: 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74 6f 20  ce of a call to 
8ee0: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64  the xSync method
8ef0: 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64 61 74  .** when the dat
8f00: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
8f10: 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73 79 6e   has [PRAGMA syn
8f20: 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20 74 6f  chronous] set to
8f30: 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65 20   OFF.)^.** Some 
8f40: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
8f50: 73 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  s need this sign
8f60: 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 6f  al in order to o
8f70: 70 65 72 61 74 65 20 63 6f 72 72 65 63 74 6c 79  perate correctly
8f80: 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47 4d 41  .** when [PRAGMA
8f90: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50   synchronous | P
8fa0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
8fb0: 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c 20 62  s=OFF] is set, b
8fc0: 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 53 65  ut most .** VFSe
8fd0: 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68  s do not need th
8fe0: 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20 73 68  is signal and sh
8ff0: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67  ould silently ig
9000: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65  nore this opcode
9010: 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
9020: 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c  s should not cal
9030: 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  l [sqlite3_file_
9040: 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20  control()] with 
9050: 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61  this.** opcode a
9060: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64  s doing so may d
9070: 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61  isrupt the opera
9080: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
9090: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a 2a  ialized VFSes.**
90a0: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65   that do require
90b0: 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69   it.  .**.** <li
90c0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
90d0: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d  WIN32_AV_RETRY]]
90e0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
90f0: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
9100: 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73  RETRY] opcode is
9110: 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75   used to configu
9120: 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20  re automatic.** 
9130: 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64  retry counts and
9140: 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63   intervals for c
9150: 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20  ertain disk I/O 
9160: 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74  operations for t
9170: 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56  he.** windows [V
9180: 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  FS] in order to 
9190: 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65  provide robustne
91a0: 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e  ss in the presen
91b0: 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69  ce of.** anti-vi
91c0: 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42  rus programs.  B
91d0: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77  y default, the w
91e0: 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20  indows VFS will 
91f0: 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c  retry file read,
9200: 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20  .** file write, 
9210: 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20  and file delete 
9220: 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f  operations up to
9230: 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20   10 times, with 
9240: 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35  a delay.** of 25
9250: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65   milliseconds be
9260: 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72  fore the first r
9270: 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68  etry and with th
9280: 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69  e delay increasi
9290: 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69  ng.** by an addi
92a0: 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73  tional 25 millis
92b0: 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68  econds with each
92c0: 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72   subsequent retr
92d0: 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  y.  This.** opco
92e0: 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20  de allows these 
92f0: 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72  two values (10 r
9300: 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69  etries and 25 mi
9310: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65  lliseconds of de
9320: 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64  lay).** to be ad
9330: 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c  justed.  The val
9340: 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20  ues are changed 
9350: 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65  for all database
9360: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
9370: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
9380: 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72  process.  The ar
9390: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
93a0: 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20  ter to an array 
93b0: 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65  of two.** intege
93c0: 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72  rs where the fir
93d0: 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 65  st integer i the
93e0: 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74   new retry count
93f0: 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a   and the second.
9400: 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68  ** integer is th
9410: 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74  e delay.  If eit
9420: 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e  her integer is n
9430: 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
9440: 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20  e setting.** is 
9450: 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20  not changed but 
9460: 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f  instead the prio
9470: 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  r value of that 
9480: 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74  setting is writt
9490: 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61  en.** into the a
94a0: 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f  rray entry, allo
94b0: 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74  wing the current
94c0: 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20   retry settings 
94d0: 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f  to be.** interro
94e0: 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e  gated.  The zDbN
94f0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
9500: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
9510: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9520: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d  TL_PERSIST_WAL]]
9530: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
9540: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
9550: 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  AL] opcode is us
9560: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65  ed to set or que
9570: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73  ry the.** persis
9580: 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74  tent [WAL | Writ
9590: 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74  e Ahead Log] set
95a0: 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c  ting.  By defaul
95b0: 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79  t, the auxiliary
95c0: 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20  .** write ahead 
95d0: 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d  log and shared m
95e0: 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64  emory files used
95f0: 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e   for transaction
9600: 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20   control.** are 
9610: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
9620: 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c  leted when the l
9630: 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e  atest connection
9640: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
9650: 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74  .** closes.  Set
9660: 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20  ting persistent 
9670: 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20  WAL mode causes 
9680: 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70  those files to p
9690: 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20  ersist after.** 
96a0: 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69  close.  Persisti
96b0: 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20  ng the files is 
96c0: 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65  useful when othe
96d0: 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74  r processes that
96e0: 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20   do not.** have 
96f0: 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e  write permission
9700: 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72   on the director
9710: 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  y containing the
9720: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
9730: 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74  ant.** to read t
9740: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9750: 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64  , as the WAL and
9760: 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66   shared memory f
9770: 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a  iles must exist.
9780: 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20  ** in order for 
9790: 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20  the database to 
97a0: 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  be readable.  Th
97b0: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
97c0: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
97d0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
97e0: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  ] for this opcod
97f0: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f  e should be a po
9800: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
9810: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74  ger..** That int
9820: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73  eger is 0 to dis
9830: 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20  able persistent 
9840: 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f  WAL mode or 1 to
9850: 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65   enable persiste
9860: 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20  nt.** WAL mode. 
9870: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20   If the integer 
9880: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69  is -1, then it i
9890: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
98a0: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  th the current.*
98b0: 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63  * WAL persistenc
98c0: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  e setting..**.**
98d0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
98e0: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
98f0: 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68  ERWRITE]].** ^Th
9900: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9910: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
9920: 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  ITE] opcode is u
9930: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
9940: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
9950: 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65  stent "powersafe
9960: 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22  -overwrite" or "
9970: 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20  PSOW" setting.  
9980: 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67  The PSOW setting
9990: 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74  .** determines t
99a0: 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  he [SQLITE_IOCAP
99b0: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
99c0: 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65  RITE] bit of the
99d0: 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61  .** xDeviceChara
99e0: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f  cteristics metho
99f0: 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70  ds. The fourth p
9a00: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
9a10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9a20: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
9a30: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
9a40: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
9a50: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
9a60: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
9a70: 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d  to disable zero-
9a80: 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31  damage mode or 1
9a90: 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d   to enable zero-
9aa0: 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20  damage.** mode. 
9ab0: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20   If the integer 
9ac0: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69  is -1, then it i
9ad0: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
9ae0: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  th the current.*
9af0: 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f  * zero-damage mo
9b00: 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a  de setting..**.*
9b10: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9b20: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d  CNTL_OVERWRITE]]
9b30: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
9b40: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
9b50: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f  ] opcode is invo
9b60: 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66  ked by SQLite af
9b70: 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61  ter opening.** a
9b80: 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69   write transacti
9b90: 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  on to indicate t
9ba0: 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69  hat, unless it i
9bb0: 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f  s rolled back fo
9bc0: 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e  r some.** reason
9bd0: 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74  , the entire dat
9be0: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20  abase file will 
9bf0: 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62  be overwritten b
9c00: 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a  y the current .*
9c10: 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54  * transaction. T
9c20: 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56  his is used by V
9c30: 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73  ACUUM operations
9c40: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9c50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
9c60: 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ME]].** ^The [SQ
9c70: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
9c80: 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62  ME] opcode can b
9c90: 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
9ca0: 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a   the names of.**
9cb0: 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20   all [VFSes] in 
9cc0: 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20  the VFS stack.  
9cd0: 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66  The names are of
9ce0: 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61   all VFS shims a
9cf0: 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  nd the.** final 
9d00: 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53  bottom-level VFS
9d10: 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74   are written int
9d20: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
9d30: 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69  d from .** [sqli
9d40: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
9d50: 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  d the result is 
9d60: 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68  stored in the ch
9d70: 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  ar* variable.** 
9d80: 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20  that the fourth 
9d90: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71  parameter of [sq
9da0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9db0: 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e  ol()] points to.
9dc0: 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69  .** The caller i
9dd0: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
9de0: 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65  r freeing the me
9df0: 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20  mory when done. 
9e00: 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20   As with.** all 
9e10: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74  file-control act
9e20: 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e  ions, there is n
9e30: 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  o guarantee that
9e40: 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61   this will actua
9e50: 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69  lly.** do anythi
9e60: 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f  ng.  Callers sho
9e70: 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74  uld initialize t
9e80: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
9e90: 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  e to a NULL.** p
9ea0: 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74  ointer in case t
9eb0: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
9ec0: 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e   is not implemen
9ed0: 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d  ted.  This file-
9ee0: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e  control.** is in
9ef0: 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e  tended for diagn
9f00: 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a  ostic use only..
9f10: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9f20: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
9f30: 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61  ].** ^Whenever a
9f40: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d   [PRAGMA] statem
9f50: 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61  ent is parsed, a
9f60: 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  n [SQLITE_FCNTL_
9f70: 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65  PRAGMA] .** file
9f80: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74   control is sent
9f90: 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71   to the open [sq
9fa0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
9fb0: 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  ct corresponding
9fc0: 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62  .** to the datab
9fd0: 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63  ase file to whic
9fe0: 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61  h the pragma sta
9ff0: 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e  tement refers. ^
a000: 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  The argument.** 
a010: 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  to the [SQLITE_F
a020: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
a030: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20  e control is an 
a040: 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e  array of.** poin
a050: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
a060: 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63  (char**) in whic
a070: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65  h the second ele
a080: 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61  ment of the arra
a090: 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  y.** is the name
a0a0: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61   of the pragma a
a0b0: 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65  nd the third ele
a0c0: 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75  ment is the argu
a0d0: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70  ment to the.** p
a0e0: 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66  ragma or NULL if
a0f0: 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20   the pragma has 
a100: 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54  no argument.  ^T
a110: 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  he handler for a
a120: 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  n.** [SQLITE_FCN
a130: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
a140: 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69  control can opti
a150: 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20  onally make the 
a160: 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a  first element.**
a170: 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61   of the char** a
a180: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f  rgument point to
a190: 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e   a string obtain
a1a0: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
a1b0: 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f  _mprintf()].** o
a1c0: 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74  r the equivalent
a1d0: 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67   and that string
a1e0: 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65   will become the
a1f0: 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70   result of the p
a200: 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20  ragma or.** the 
a210: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66  error message if
a220: 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c   the pragma fail
a230: 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  s. ^If the.** [S
a240: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
a250: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
a260: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
a270: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e  _NOTFOUND], then
a280: 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41   normal .** [PRA
a290: 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20  GMA] processing 
a2a0: 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20  continues.  ^If 
a2b0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
a2c0: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c  L_PRAGMA].** fil
a2d0: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
a2e0: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
a2f0: 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61  hen the parser a
a300: 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
a310: 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c  ** VFS has handl
a320: 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74  ed the PRAGMA it
a330: 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72  self and the par
a340: 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20  ser generates a 
a350: 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65  no-op.** prepare
a360: 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49  d statement.  ^I
a370: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  f the [SQLITE_FC
a380: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
a390: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
a3a0: 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63  .** any result c
a3b0: 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ode other than [
a3c0: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53  SQLITE_OK] or [S
a3d0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
a3e0: 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74   that means.** t
a3f0: 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f  hat the VFS enco
a400: 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72  untered an error
a410: 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20   while handling 
a420: 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64  the [PRAGMA] and
a430: 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74   the.** compilat
a440: 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d  ion of the PRAGM
a450: 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20  A fails with an 
a460: 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51  error.  ^The [SQ
a470: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
a480: 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72  A].** file contr
a490: 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 65  ol occurs at the
a4a0: 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72   beginning of pr
a4b0: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61  agma statement a
a4c0: 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a  nalysis and so.*
a4d0: 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20  * it is able to 
a4e0: 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69  override built-i
a4f0: 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65  n [PRAGMA] state
a500: 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ments..**.** <li
a510: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a520: 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a  BUSYHANDLER]].**
a530: 20 5e 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74   ^This file-cont
a540: 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  rol may be invok
a550: 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20  ed by SQLite on 
a560: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
a570: 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72  e handle.** shor
a580: 74 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 20  tly after it is 
a590: 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20  opened in order 
a5a0: 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 73  to provide a cus
a5b0: 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 63  tom VFS with acc
a5c0: 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f  ess.** to the co
a5d0: 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68  nnections busy-h
a5e0: 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  andler callback.
a5f0: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
a600: 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a   of type (void *
a610: 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79  *).** - an array
a620: 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29   of two (void *)
a630: 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72   values. The fir
a640: 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75  st (void *) actu
a650: 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74  ally points.** t
a660: 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20  o a function of 
a670: 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f  type (int (*)(vo
a680: 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72  id *)). In order
a690: 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63   to invoke the c
a6a0: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75  onnections.** bu
a6b0: 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73  sy-handler, this
a6c0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64   function should
a6d0: 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
a6e0: 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69   the second (voi
a6f0: 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61  d *) in.** the a
a700: 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79  rray as the only
a710: 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74   argument. If it
a720: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
a730: 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72  o, then the oper
a740: 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
a750: 62 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 69  be retried. If i
a760: 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20  t returns zero, 
a770: 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73  the custom VFS s
a780: 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68  hould abandon th
a790: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65  e.** current ope
a7a0: 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ration..**.** <l
a7b0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a7c0: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a  _TEMPFILENAME]].
a7d0: 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20  ** ^Application 
a7e0: 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 69 73 20  can invoke this 
a7f0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 74 6f 20  file-control to 
a800: 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65  have SQLite gene
a810: 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72  rate a.** tempor
a820: 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69  ary filename usi
a830: 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  ng the same algo
a840: 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f  rithm that is fo
a850: 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61  llowed to genera
a860: 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
a870: 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45  filenames for TE
a880: 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74  MP tables and ot
a890: 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65  her internal use
a8a0: 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d  s.  The.** argum
a8b0: 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ent should be a 
a8c0: 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c  char** which wil
a8d0: 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68  l be filled with
a8e0: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   the filename.**
a8f0: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
a900: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
a910: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
a920: 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c  oc()].  The call
a930: 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76  er should.** inv
a940: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
a950: 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75  e()] on the resu
a960: 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65  lt to avoid a me
a970: 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a  mory leak..**.**
a980: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
a990: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  NTL_MMAP_SIZE]].
a9a0: 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
a9b0: 69 73 20 61 73 73 75 6d 65 64 20 74 6f 20 70 6f  is assumed to po
a9c0: 69 6e 74 20 74 6f 20 61 20 76 61 6c 75 65 20 6f  int to a value o
a9d0: 66 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69  f type sqlite3_i
a9e0: 6e 74 36 34 2e 20 41 6e 0a 2a 2a 20 61 64 76 69  nt64. An.** advi
a9f0: 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 61 6d 6f  sory maximum amo
aa00: 75 6e 74 20 6f 66 20 74 68 69 73 20 66 69 6c 65  unt of this file
aa10: 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 20 69   to memory map i
aa20: 6e 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  n bytes..**.** <
aa30: 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /ul>.*/.#define 
aa40: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
aa50: 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20 20  KSTATE          
aa60: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
aa70: 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52  QLITE_GET_LOCKPR
aa80: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 20 20  OXYFILE         
aa90: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
aaa0: 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_SET_LOCKPRO
aab0: 58 59 46 49 4c 45 20 20 20 20 20 20 20 20 20 20  XYFILE          
aac0: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
aad0: 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20  ITE_LAST_ERRNO  
aae0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
aaf0: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
ab00: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
ab10: 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NT              
ab20: 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
ab30: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
ab40: 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
ab50: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
ab60: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
ab70: 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20 37  TER            7
ab80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ab90: 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54  FCNTL_SYNC_OMITT
aba0: 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38 0a  ED            8.
abb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
abc0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
abd0: 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a 23  TRY          9.#
abe0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
abf0: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20  NTL_PERSIST_WAL 
ac00: 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64             10.#d
ac10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
ac20: 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  TL_OVERWRITE    
ac30: 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 65            11.#de
ac40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
ac50: 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20  L_VFSNAME       
ac60: 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 66           12.#def
ac70: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
ac80: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
ac90: 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66 69  RITE    13.#defi
aca0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
acb0: 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20  PRAGMA          
acc0: 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e         14.#defin
acd0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42  e SQLITE_FCNTL_B
ace0: 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20  USYHANDLER      
acf0: 20 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65        15.#define
ad00: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45   SQLITE_FCNTL_TE
ad10: 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20  MPFILENAME      
ad20: 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20       16.#define 
ad30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
ad40: 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20  P_SIZE          
ad50: 20 20 20 20 31 38 0a 0a 2f 2a 0a 2a 2a 20 43 41      18../*.** CA
ad60: 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61  PI3REF: Mutex Ha
ad70: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  ndle.**.** The m
ad80: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
ad90: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
ada0: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
adb0: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
adc0: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
add0: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
ade0: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
adf0: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
ae00: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
ae10: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
ae20: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
ae30: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
ae40: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
ae50: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
ae60: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
ae70: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
ae80: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
ae90: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
aea0: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
aeb0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
aec0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
aed0: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
aee0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
aef0: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
af00: 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  t.**.** An insta
af10: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74  nce of the sqlit
af20: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65  e3_vfs object de
af30: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
af40: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ace between.** t
af50: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61  he SQLite core a
af60: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
af70: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
af80: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a  em.  The "vfs".*
af90: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  * in the name of
afa0: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e   the object stan
afb0: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20  ds for "virtual 
afc0: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53  file system".  S
afd0: 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c  ee.** the [VFS |
afe0: 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69   VFS documentati
aff0: 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20  on] for further 
b000: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
b010: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20  ** The value of 
b020: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
b030: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20  ld is initially 
b040: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  1 but may be lar
b050: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  ger in.** future
b060: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
b070: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ite.  Additional
b080: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
b090: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a  ppended to this.
b0a0: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74  ** object when t
b0b0: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
b0c0: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20  e is increased. 
b0d0: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73   Note that the s
b0e0: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74  tructure.** of t
b0f0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
b100: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e  bject changes in
b110: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
b120: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69   between.** SQLi
b130: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39  te version 3.5.9
b140: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79   and 3.6.0 and y
b150: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  et the iVersion 
b160: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a  field was not.**
b170: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a   modified..**.**
b180: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69   The szOsFile fi
b190: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20  eld is the size 
b1a0: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65  of the subclasse
b1b0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  d [sqlite3_file]
b1c0: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73  .** structure us
b1d0: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20  ed by this VFS. 
b1e0: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74   mxPathname is t
b1f0: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
b200: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61  h of.** a pathna
b210: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a  me in this VFS..
b220: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64  **.** Registered
b230: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
b240: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e  ects are kept on
b250: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66   a linked list f
b260: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  ormed by.** the 
b270: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20  pNext pointer.  
b280: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
b290: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20  _register()].** 
b2a0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  and [sqlite3_vfs
b2b0: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69  _unregister()] i
b2c0: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65  nterfaces manage
b2d0: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e   this list.** in
b2e0: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77   a thread-safe w
b2f0: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ay.  The [sqlite
b300: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e  3_vfs_find()] in
b310: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63  terface.** searc
b320: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e  hes the list.  N
b330: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69  either the appli
b340: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20  cation code nor 
b350: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65  the VFS.** imple
b360: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
b370: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70   use the pNext p
b380: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
b390: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73  e pNext field is
b3a0: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20   the only field 
b3b0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
b3c0: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  fs.** structure 
b3d0: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
b3e0: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53   ever modify.  S
b3f0: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20  QLite will only 
b400: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64  access.** or mod
b410: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77  ify this field w
b420: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70  hile holding a p
b430: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63  articular static
b440: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61   mutex..** The a
b450: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
b460: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61  d never modify a
b470: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74  nything within t
b480: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
b490: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68  * object once th
b4a0: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65  e object has bee
b4b0: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a  n registered..**
b4c0: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69  .** The zName fi
b4d0: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61  eld holds the na
b4e0: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f  me of the VFS mo
b4f0: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20  dule.  The name 
b500: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75  must.** be uniqu
b510: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53  e across all VFS
b520: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20   modules..**.** 
b530: 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f  [[sqlite3_vfs.xO
b540: 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65  pen]].** ^SQLite
b550: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
b560: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
b570: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
b580: 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61  n.** is either a
b590: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72   NULL pointer or
b5a0: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
b5b0: 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61  .** from xFullPa
b5c0: 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e  thname() with an
b5d0: 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78   optional suffix
b5e0: 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61   added..** ^If a
b5f0: 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64   suffix is added
b600: 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   to the zFilenam
b610: 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20  e parameter, it 
b620: 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20  will.** consist 
b630: 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20  of a single "-" 
b640: 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77  character follow
b650: 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68  ed by no more th
b660: 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75  an.** 11 alphanu
b670: 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22  meric and/or "-"
b680: 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20   characters..** 
b690: 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20  ^SQLite further 
b6a0: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a  guarantees that.
b6b0: 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69  ** the string wi
b6c0: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20  ll be valid and 
b6d0: 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20  unchanged until 
b6e0: 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63  xClose() is.** c
b6f0: 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f  alled. Because o
b700: 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  f the previous s
b710: 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  entence,.** the 
b720: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63  [sqlite3_file] c
b730: 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20  an safely store 
b740: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
b750: 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20  .** filename if 
b760: 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65  it needs to reme
b770: 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d  mber the filenam
b780: 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  e for some reaso
b790: 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69  n..** If the zFi
b7a0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
b7b0: 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e   to xOpen is a N
b7c0: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
b7d0: 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69   xOpen.** must i
b7e0: 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65  nvent its own te
b7f0: 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72  mporary name for
b800: 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65   the file.  ^Whe
b810: 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46  never the .** xF
b820: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
b830: 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c  r is NULL it wil
b840: 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61  l also be the ca
b850: 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66  se that the.** f
b860: 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77  lags parameter w
b870: 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  ill include [SQL
b880: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
b890: 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54  NCLOSE]..**.** T
b8a0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
b8b0: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63  t to xOpen() inc
b8c0: 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73  ludes all bits s
b8d0: 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61  et in.** the fla
b8e0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  gs argument to [
b8f0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
b900: 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69  )].  Or if [sqli
b910: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f  te3_open()].** o
b920: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
b930: 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68  6()] is used, th
b940: 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65  en flags include
b950: 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53  s at least.** [S
b960: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
b970: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
b980: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a  OPEN_CREATE]. .*
b990: 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65  * If xOpen() ope
b9a0: 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f  ns a file read-o
b9b0: 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73  nly then it sets
b9c0: 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a   *pOutFlags to.*
b9d0: 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  * include [SQLIT
b9e0: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
b9f0: 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e  .  Other bits in
ba00: 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20   *pOutFlags may 
ba10: 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  be set..**.** ^(
ba20: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f  SQLite will also
ba30: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
ba40: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
ba50: 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a  to the xOpen().*
ba60: 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e  * call, dependin
ba70: 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20  g on the object 
ba80: 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a  being opened:.**
ba90: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
baa0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
bab0: 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  AIN_DB].** <li> 
bac0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
bad0: 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  IN_JOURNAL].** <
bae0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
baf0: 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_TEMP_DB].** <l
bb00: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
bb10: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _TEMP_JOURNAL].*
bb20: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
bb30: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
bb40: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
bb50: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
bb60: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
bb70: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
bb80: 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  R_JOURNAL].** <l
bb90: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
bba0: 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  _WAL].** </ul>)^
bbb0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20  .**.** The file 
bbc0: 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  I/O implementati
bbd0: 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f  on can use the o
bbe0: 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73  bject type flags
bbf0: 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68   to.** change th
bc00: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77  e way it deals w
bc10: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20  ith files.  For 
bc20: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
bc30: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  ication.** that 
bc40: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62  does not care ab
bc50: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65  out crash recove
bc60: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d  ry or rollback m
bc70: 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65  ight make.** the
bc80: 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e   open of a journ
bc90: 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e  al file a no-op.
bca0: 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73    Writes to this
bcb0: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a   journal would.*
bcc0: 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73  * also be no-ops
bcd0: 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70  , and any attemp
bce0: 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f  t to read the jo
bcf0: 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75  urnal would retu
bd00: 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45  rn.** SQLITE_IOE
bd10: 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c  RR.  Or the impl
bd20: 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74  ementation might
bd30: 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20   recognize that 
bd40: 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  a database.** fi
bd50: 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67  le will be doing
bd60: 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65   page-aligned se
bd70: 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77  ctor reads and w
bd80: 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f  rites in a rando
bd90: 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73  m.** order and s
bda0: 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75  et up its I/O su
bdb0: 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e  bsystem accordin
bdc0: 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  gly..**.** SQLit
bdd0: 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64  e might also add
bde0: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
bdf0: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
be00: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a  he xOpen method:
be10: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
be20: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
be30: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
be40: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
be50: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a  OPEN_EXCLUSIVE].
be60: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
be70: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
be80: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66  DELETEONCLOSE] f
be90: 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69  lag means the fi
bea0: 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  le should be.** 
beb0: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20  deleted when it 
bec0: 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65  is closed.  ^The
bed0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
bee0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
bef0: 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20  will be set for 
bf00: 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61  TEMP databases a
bf10: 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c  nd their journal
bf20: 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20  s, transient.** 
bf30: 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73  databases, and s
bf40: 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a  ubjournals..**.*
bf50: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
bf60: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66  PEN_EXCLUSIVE] f
bf70: 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73  lag is always us
bf80: 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f  ed in conjunctio
bf90: 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  n.** with the [S
bfa0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
bfb0: 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61  E] flag, which a
bfc0: 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79  re both directly
bfd0: 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f  .** analogous to
bfe0: 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20   the O_EXCL and 
bff0: 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66  O_CREAT flags of
c000: 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28   the POSIX open(
c010: 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53  ).** API.  The S
c020: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
c030: 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20  SIVE flag, when 
c040: 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20  paired with the 
c050: 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  .** SQLITE_OPEN_
c060: 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20  CREATE, is used 
c070: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
c080: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77   file should alw
c090: 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65  ays.** be create
c0a0: 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69  d, and that it i
c0b0: 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74  s an error if it
c0c0: 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e   already exists.
c0d0: 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74  .** It is <i>not
c0e0: 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64  </i> used to ind
c0f0: 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73  icate the file s
c100: 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20  hould be opened 
c110: 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76  .** for exclusiv
c120: 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  e access..**.** 
c130: 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69  ^At least szOsFi
c140: 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  le bytes of memo
c150: 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64  ry are allocated
c160: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f   by SQLite.** to
c170: 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69   hold the  [sqli
c180: 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74  te3_file] struct
c190: 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68  ure passed as th
c1a0: 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d  e third.** argum
c1b0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54  ent to xOpen.  T
c1c0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
c1d0: 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f  does not have to
c1e0: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  .** allocate the
c1f0: 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73   structure; it s
c200: 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20  hould just fill 
c210: 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61  it in.  Note tha
c220: 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d  t.** the xOpen m
c230: 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74  ethod must set t
c240: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
c250: 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68  pMethods to eith
c260: 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73  er.** a valid [s
c270: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
c280: 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20  s] object or to 
c290: 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73  NULL.  xOpen mus
c2a0: 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65  t do.** this eve
c2b0: 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61  n if the open fa
c2c0: 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70  ils.  SQLite exp
c2d0: 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71  ects that the sq
c2e0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
c2f0: 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77  ods.** element w
c300: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74  ill be valid aft
c310: 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73  er xOpen returns
c320: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
c330: 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72  he success.** or
c340: 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20   failure of the 
c350: 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  xOpen call..**.*
c360: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
c370: 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68  xAccess]].** ^Th
c380: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
c390: 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61   to xAccess() ma
c3a0: 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43  y be [SQLITE_ACC
c3b0: 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74  ESS_EXISTS].** t
c3c0: 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65  o test for the e
c3d0: 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69  xistence of a fi
c3e0: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
c3f0: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d  CCESS_READWRITE]
c400: 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74   to.** test whet
c410: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65  her a file is re
c420: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
c430: 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ble, or [SQLITE_
c440: 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20  ACCESS_READ].** 
c450: 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20  to test whether 
c460: 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61  a file is at lea
c470: 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54  st readable.   T
c480: 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61  he file can be a
c490: 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  .** directory..*
c4a0: 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  *.** ^SQLite wil
c4b0: 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74  l always allocat
c4c0: 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74  e at least mxPat
c4d0: 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f  hname+1 bytes fo
c4e0: 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20  r the.** output 
c4f0: 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68  buffer xFullPath
c500: 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74  name.  The exact
c510: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74   size of the out
c520: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
c530: 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20   also passed as 
c540: 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  a parameter to b
c550: 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66  oth  methods. If
c560: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
c570: 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72  er.** is not lar
c580: 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49  ge enough, [SQLI
c590: 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f  TE_CANTOPEN] sho
c5a0: 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
c5b0: 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a   Since this is.*
c5c0: 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66  * handled as a f
c5d0: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51  atal error by SQ
c5e0: 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d  Lite, vfs implem
c5f0: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
c600: 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20   endeavor.** to 
c610: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20  prevent this by 
c620: 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61  setting mxPathna
c630: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65  me to a sufficie
c640: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65  ntly large value
c650: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ..**.** The xRan
c660: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65  domness(), xSlee
c670: 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d  p(), xCurrentTim
c680: 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e  e(), and xCurren
c690: 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20  tTimeInt64().** 
c6a0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e  interfaces are n
c6b0: 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61  ot strictly a pa
c6c0: 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79  rt of the filesy
c6d0: 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61  stem, but they a
c6e0: 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69  re.** included i
c6f0: 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74  n the VFS struct
c700: 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65  ure for complete
c710: 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61  ness..** The xRa
c720: 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74  ndomness() funct
c730: 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ion attempts to 
c740: 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79  return nBytes by
c750: 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71  tes.** of good-q
c760: 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73  uality randomnes
c770: 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68  s into zOut.  Th
c780: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  e return value i
c790: 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20  s.** the actual 
c7a0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
c7b0: 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  of randomness ob
c7c0: 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78  tained..** The x
c7d0: 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63  Sleep() method c
c7e0: 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e  auses the callin
c7f0: 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65  g thread to slee
c800: 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73  p for at.** leas
c810: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
c820: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76  microseconds giv
c830: 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65  en.  ^The xCurre
c840: 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68  ntTime().** meth
c850: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c  od returns a Jul
c860: 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66  ian Day Number f
c870: 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  or the current d
c880: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a  ate and time as.
c890: 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ** a floating po
c8a0: 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54  int value..** ^T
c8b0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
c8c0: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65  nt64() method re
c8d0: 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74  turns, as an int
c8e0: 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e  eger, the Julian
c8f0: 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d  .** Day Number m
c900: 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34  ultiplied by 864
c910: 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65  00000 (the numbe
c920: 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
c930: 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f  s in .** a 24-ho
c940: 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53  ur day).  .** ^S
c950: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
c960: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
c970: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f  nt64() method to
c980: 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74   get the current
c990: 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d  .** date and tim
c9a0: 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64  e if that method
c9b0: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69   is available (i
c9c0: 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20  f iVersion is 2 
c9d0: 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61  or .** greater a
c9e0: 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  nd the function 
c9f0: 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
ca00: 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61  ULL) and will fa
ca10: 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43  ll back.** to xC
ca20: 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20  urrentTime() if 
ca30: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
ca40: 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62  4() is unavailab
ca50: 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  le..**.** ^The x
ca60: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c  SetSystemCall(),
ca70: 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xGetSystemCall(
ca80: 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74  ), and xNestSyst
ca90: 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61  emCall() interfa
caa0: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75  ces.** are not u
cab0: 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74  sed by the SQLit
cac0: 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f  e core.  These o
cad0: 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63  ptional interfac
cae0: 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a  es are provided.
caf0: 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73  ** by some VFSes
cb00: 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74   to facilitate t
cb10: 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46  esting of the VF
cb20: 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72  S code. By overr
cb30: 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d  iding .** system
cb40: 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63   calls with func
cb50: 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20  tions under its 
cb60: 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20  control, a test 
cb70: 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73  program can.** s
cb80: 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61  imulate faults a
cb90: 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69  nd error conditi
cba0: 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f  ons that would o
cbb0: 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66  therwise be diff
cbc0: 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f  icult.** or impo
cbd0: 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65  ssible to induce
cbe0: 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79  .  The set of sy
cbf0: 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20  stem calls that 
cc00: 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
cc10: 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d  n.** varies from
cc20: 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74   one VFS to anot
cc30: 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e  her, and from on
cc40: 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  e version of the
cc50: 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65   same VFS to the
cc60: 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  .** next.  Appli
cc70: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65  cations that use
cc80: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
cc90: 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72  s must be prepar
cca0: 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72  ed for any.** or
ccb0: 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e   all of these in
ccc0: 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e  terfaces to be N
ccd0: 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72  ULL or for their
cce0: 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61   behavior to cha
ccf0: 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20  nge.** from one 
cd00: 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e  release to the n
cd10: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
cd20: 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65  ns must not atte
cd30: 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a  mpt to access.**
cd40: 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65   any of these me
cd50: 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65  thods if the iVe
cd60: 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53  rsion of the VFS
cd70: 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e   is less than 3.
cd80: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
cd90: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73  ct sqlite3_vfs s
cda0: 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65  qlite3_vfs;.type
cdb0: 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
cdc0: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28  e3_syscall_ptr)(
cdd0: 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71  void);.struct sq
cde0: 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e  lite3_vfs {.  in
cdf0: 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20  t iVersion;     
ce00: 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74         /* Struct
ce10: 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  ure version numb
ce20: 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29  er (currently 3)
ce30: 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69   */.  int szOsFi
ce40: 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  le;            /
ce50: 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61  * Size of subcla
ce60: 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c  ssed sqlite3_fil
ce70: 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74  e */.  int mxPat
ce80: 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20  hname;          
ce90: 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20  /* Maximum file 
cea0: 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20  pathname length 
ceb0: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73  */.  sqlite3_vfs
cec0: 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a   *pNext;      /*
ced0: 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64   Next registered
cee0: 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20   VFS */.  const 
cef0: 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20  char *zName;    
cf00: 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
cf10: 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20  is virtual file 
cf20: 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64  system */.  void
cf30: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
cf40: 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20       /* Pointer 
cf50: 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  to application-s
cf60: 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a  pecific data */.
cf70: 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
cf80: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
cf90: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
cfa0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20  sqlite3_file*,. 
cfb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
cfc0: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f  t flags, int *pO
cfd0: 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  utFlags);.  int 
cfe0: 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74  (*xDelete)(sqlit
cff0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
d000: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
d010: 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20  syncDir);.  int 
d020: 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74  (*xAccess)(sqlit
d030: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
d040: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
d050: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73  flags, int *pRes
d060: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
d070: 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c  ullPathname)(sql
d080: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
d090: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
d0a0: 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f  t nOut, char *zO
d0b0: 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ut);.  void *(*x
d0c0: 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  DlOpen)(sqlite3_
d0d0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
d0e0: 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20   *zFilename);.  
d0f0: 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29  void (*xDlError)
d100: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
d110: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
d120: 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64  zErrMsg);.  void
d130: 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c   (*(*xDlSym)(sql
d140: 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c  ite3_vfs*,void*,
d150: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79   const char *zSy
d160: 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20  mbol))(void);.  
d170: 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29  void (*xDlClose)
d180: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76  (sqlite3_vfs*, v
d190: 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  oid*);.  int (*x
d1a0: 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69  Randomness)(sqli
d1b0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
d1c0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  yte, char *zOut)
d1d0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70  ;.  int (*xSleep
d1e0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
d1f0: 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73  int microseconds
d200: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  );.  int (*xCurr
d210: 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33  entTime)(sqlite3
d220: 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b  _vfs*, double*);
d230: 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73  .  int (*xGetLas
d240: 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  tError)(sqlite3_
d250: 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20  vfs*, int, char 
d260: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
d270: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
d280: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31  are in version 1
d290: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
d2a0: 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64  fs object.  ** d
d2b0: 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73  efinition.  Thos
d2c0: 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72  e that follow ar
d2d0: 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69  e added in versi
d2e0: 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20  on 2 or later.  
d2f0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  */.  int (*xCurr
d300: 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71  entTimeInt64)(sq
d310: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69  lite3_vfs*, sqli
d320: 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f  te3_int64*);.  /
d330: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
d340: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
d350: 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32  versions 1 and 2
d360: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
d370: 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
d380: 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20  Those below are 
d390: 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e  for version 3 an
d3a0: 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a  d greater..  */.
d3b0: 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74    int (*xSetSyst
d3c0: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
d3d0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
d3e0: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
d3f0: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20  _syscall_ptr);. 
d400: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
d410: 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65  _ptr (*xGetSyste
d420: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
d430: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
d440: 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74  *zName);.  const
d450: 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79   char *(*xNextSy
d460: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
d470: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
d480: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a  ar *zName);.  /*
d490: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
d4a0: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
d4b0: 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67  ersions 1 throug
d4c0: 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74  h 3 of the sqlit
d4d0: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
d4e0: 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61  ** New fields ma
d4f0: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e  y be appended in
d500: 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73   figure versions
d510: 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a  .  The iVersion.
d520: 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20    ** value will 
d530: 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76  increment whenev
d540: 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e  er this happens.
d550: 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a   .  */.};../*.**
d560: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
d570: 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73   for the xAccess
d580: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
d590: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
d5a0: 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65  constants can be
d5b0: 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69   used as the thi
d5c0: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
d5d0: 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ** the xAccess m
d5e0: 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c  ethod of an [sql
d5f0: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
d600: 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e  .  They determin
d610: 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f  e.** what kind o
d620: 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
d630: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
d640: 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e   is looking for.
d650: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
d660: 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74  ACCESS_EXISTS, t
d670: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
d680: 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63  d.** simply chec
d690: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
d6a0: 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57  ile exists..** W
d6b0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
d6c0: 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
d6d0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
d6e0: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
d6f0: 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65  r the named dire
d700: 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65  ctory is both re
d710: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
d720: 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72  ble.** (in other
d730: 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73   words, if files
d740: 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72   can be added, r
d750: 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61  emoved, and rena
d760: 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  med within.** th
d770: 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a  e directory)..**
d780: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
d790: 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e  SS_READWRITE con
d7a0: 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74  stant is current
d7b0: 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20  ly used only by 
d7c0: 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f  the.** [temp_sto
d7d0: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
d7e0: 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69  gma], though thi
d7f0: 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69  s could change i
d800: 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65  n a future.** re
d810: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
d820: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
d830: 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
d840: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
d850: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
d860: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
d870: 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c  adable.  The SQL
d880: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
d890: 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63  constant is.** c
d8a0: 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c  urrently unused,
d8b0: 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74   though it might
d8c0: 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75   be used in a fu
d8d0: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
d8e0: 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  ** SQLite..*/.#d
d8f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
d900: 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a  ESS_EXISTS    0.
d910: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
d920: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
d930: 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50  1   /* Used by P
d940: 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65  RAGMA temp_store
d950: 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64  _directory */.#d
d960: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
d970: 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20  ESS_READ      2 
d980: 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a    /* Unused */..
d990: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
d9a0: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53  Flags for the xS
d9b0: 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f  hmLock VFS metho
d9c0: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
d9d0: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
d9e0: 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f  define the vario
d9f0: 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61  us locking opera
da00: 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64  tions.** allowed
da10: 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b   by the xShmLock
da20: 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69   method of [sqli
da30: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e  te3_io_methods].
da40: 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69    The.** followi
da50: 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20  ng are the only 
da60: 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f  legal combinatio
da70: 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74  ns of flags to t
da80: 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d  he.** xShmLock m
da90: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
daa0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  >.** <li>  SQLIT
dab0: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
dac0: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
dad0: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
dae0: 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
daf0: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
db00: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
db10: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
db20: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
db30: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
db40: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
db50: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
db60: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57  ** </ul>.**.** W
db70: 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74  hen unlocking, t
db80: 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f  he same SHARED o
db90: 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  r EXCLUSIVE flag
dba0: 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65   must be supplie
dbb0: 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65  d as.** was give
dbc0: 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 70  n no the corresp
dbd0: 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a  onding lock.  .*
dbe0: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
dbf0: 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61  k method can tra
dc00: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
dc10: 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41  unlocked and SHA
dc20: 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65  RED or.** betwee
dc30: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45  n unlocked and E
dc40: 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61  XCLUSIVE.  It ca
dc50: 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20  nnot transition 
dc60: 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a  between SHARED.*
dc70: 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  * and EXCLUSIVE.
dc80: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
dc90: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20  TE_SHM_UNLOCK   
dca0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
dcb0: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20  LITE_SHM_LOCK   
dcc0: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
dcd0: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
dce0: 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e  D       4.#defin
dcf0: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  e SQLITE_SHM_EXC
dd00: 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a  LUSIVE    8../*.
dd10: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78  ** CAPI3REF: Max
dd20: 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e  imum xShmLock in
dd30: 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  dex.**.** The xS
dd40: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e  hmLock method on
dd50: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
dd60: 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61  hods] may use va
dd70: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
dd80: 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72  0 and this upper
dd90: 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f   bound as its "o
dda0: 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e  ffset" argument.
ddb0: 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
ddc0: 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61  ore will never a
ddd0: 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72  ttempt to acquir
dde0: 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a  e or release a.*
ddf0: 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f  * lock outside o
de00: 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a  f this range.*/.
de10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
de20: 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  HM_NLOCK        
de30: 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  8.../*.** CAPI3R
de40: 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54  EF: Initialize T
de50: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
de60: 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  y.**.** ^The sql
de70: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
de80: 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61  ) routine initia
de90: 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c  lizes the.** SQL
dea0: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54  ite library.  ^T
deb0: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
dec0: 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  own() routine.**
ded0: 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79   deallocates any
dee0: 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20   resources that 
def0: 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  were allocated b
df00: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
df10: 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65  lize()..** These
df20: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
df30: 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e  signed to aid in
df40: 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
df50: 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73  ization and.** s
df60: 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64  hutdown on embed
df70: 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f  ded systems.  Wo
df80: 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63  rkstation applic
df90: 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20  ations using.** 
dfa0: 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20  SQLite normally 
dfb0: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69  do not need to i
dfc0: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20  nvoke either of 
dfd0: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
dfe0: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
dff0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
e000: 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  ze() is an "effe
e010: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
e020: 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73  t is.** the firs
e030: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
e040: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
e050: 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68  nvoked during th
e060: 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a  e lifetime of.**
e070: 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72   the process, or
e080: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
e090: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
e0a0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
e0b0: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c   invoked.** foll
e0c0: 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  owing a call to 
e0d0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
e0e0: 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65  ().  ^(Only an e
e0f0: 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a  ffective call.**
e100: 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   of sqlite3_init
e110: 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e  ialize() does an
e120: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
e130: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c  .  All other cal
e140: 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65  ls.** are harmle
e150: 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
e160: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
e170: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
e180: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
e190: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20  " call if it is 
e1a0: 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c  the first.** cal
e1b0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
e1c0: 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68  tdown() since th
e1d0: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69  e last sqlite3_i
e1e0: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28  nitialize().  ^(
e1f0: 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63  Only.** an effec
e200: 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c  tive call to sql
e210: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
e220: 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69  does any deiniti
e230: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c  alization..** Al
e240: 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61  l other valid ca
e250: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  lls to sqlite3_s
e260: 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61  hutdown() are ha
e270: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
e280: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
e290: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
e2a0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72  interface is thr
e2b0: 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c  eadsafe, but sql
e2c0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
e2d0: 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20  ** is not.  The 
e2e0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
e2f0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73  () interface mus
e300: 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  t only be called
e310: 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c   from a.** singl
e320: 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f  e thread.  All o
e330: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
e340: 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20  nnections] must 
e350: 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c  be closed and al
e360: 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74  l.** other SQLit
e370: 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74  e resources must
e380: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
e390: 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e  prior to invokin
e3a0: 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75  g.** sqlite3_shu
e3b0: 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41  tdown()..**.** A
e3c0: 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67  mong other thing
e3d0: 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74  s, ^sqlite3_init
e3e0: 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e  ialize() will in
e3f0: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
e400: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69  os_init().  Simi
e410: 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f  larly, ^sqlite3_
e420: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69  shutdown().** wi
e430: 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ll invoke sqlite
e440: 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a  3_os_end()..**.*
e450: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
e460: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
e470: 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
e480: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
e490: 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73  ss..** ^If for s
e4a0: 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69  ome reason, sqli
e4b0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
e4c0: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e   is unable to in
e4d0: 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20  itialize.** the 
e4e0: 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73  library (perhaps
e4f0: 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
e500: 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64   allocate a need
e510: 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68  ed resource such
e520: 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20  .** as a mutex) 
e530: 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65  it returns an [e
e540: 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72  rror code] other
e550: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
e560: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
e570: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
e580: 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  () routine is ca
e590: 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  lled internally 
e5a0: 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  by many other.**
e5b0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
e5c0: 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70  es so that an ap
e5d0: 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c  plication usuall
e5e0: 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  y does not need 
e5f0: 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
e600: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e610: 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72  ) directly.  For
e620: 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74   example, [sqlit
e630: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61  e3_open()].** ca
e640: 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  lls sqlite3_init
e650: 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20  ialize() so the 
e660: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
e670: 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
e680: 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ally.** initiali
e690: 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  zed when [sqlite
e6a0: 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c  3_open()] is cal
e6b0: 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f  led if it has no
e6c0: 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64  t be initialized
e6d0: 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48  .** already.  ^H
e6e0: 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74  owever, if SQLit
e6f0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
e700: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
e710: 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a  MIT_AUTOINIT].**
e720: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
e730: 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61  tion, then the a
e740: 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74  utomatic calls t
e750: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
e760: 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d  lize().** are om
e770: 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70  itted and the ap
e780: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63  plication must c
e790: 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  all sqlite3_init
e7a0: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
e7b0: 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73  y.** prior to us
e7c0: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
e7d0: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
e7e0: 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72   For maximum por
e7f0: 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20  tability,.** it 
e800: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
e810: 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
e820: 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73   always invoke s
e830: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
e840: 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20  e().** directly 
e850: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
e860: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
e870: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75  interface.  Futu
e880: 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f  re releases.** o
e890: 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71  f SQLite may req
e8a0: 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f  uire this.  In o
e8b0: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
e8c0: 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74  behavior exhibit
e8d0: 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  ed.** when SQLit
e8e0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
e8f0: 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  th [SQLITE_OMIT_
e900: 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20  AUTOINIT] might 
e910: 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65  become the.** de
e920: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
e930: 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
e940: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
e950: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
e960: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75  e3_os_init() rou
e970: 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74  tine does operat
e980: 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
e990: 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  fic.** initializ
e9a0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c  ation of the SQL
e9b0: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
e9c0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
e9d0: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e  ().** routine un
e9e0: 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20  does the effect 
e9f0: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
ea00: 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74  it().  Typical t
ea10: 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65  asks.** performe
ea20: 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69  d by these routi
ea30: 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f  nes include allo
ea40: 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f  cation or deallo
ea50: 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61  cation.** of sta
ea60: 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69  tic resources, i
ea70: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
ea80: 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
ea90: 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70  s,.** setting up
eaa0: 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69   a default [sqli
eab0: 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c  te3_vfs] module,
eac0: 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a   or setting up.*
ead0: 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  * a default conf
eae0: 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20  iguration using 
eaf0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
eb00: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  )]..**.** The ap
eb10: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
eb20: 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69   never invoke ei
eb30: 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ther sqlite3_os_
eb40: 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  init().** or sql
eb50: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69  ite3_os_end() di
eb60: 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70  rectly.  The app
eb70: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
eb80: 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  only invoke.** s
eb90: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
eba0: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
ebb0: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65  shutdown().  The
ebc0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
ebd0: 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
ebe0: 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61  is called automa
ebf0: 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
ec00: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
ec10: 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  and.** sqlite3_o
ec20: 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65  s_end() is calle
ec30: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75  d by sqlite3_shu
ec40: 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70  tdown().  Approp
ec50: 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  riate.** impleme
ec60: 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c  ntations for sql
ec70: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
ec80: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
ec90: 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74  d().** are built
eca0: 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65   into SQLite whe
ecb0: 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64  n it is compiled
ecc0: 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f   for Unix, Windo
ecd0: 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20  ws, or OS/2..** 
ece0: 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69  When [custom bui
ecf0: 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20  lds | built for 
ed00: 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d  other platforms]
ed10: 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b  .** (using the [
ed20: 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d  SQLITE_OS_OTHER=
ed30: 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  1] compile-time.
ed40: 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61  ** option) the a
ed50: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
ed60: 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c  supply a suitabl
ed70: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
ed80: 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
ed90: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
eda0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20  lite3_os_end(). 
edb0: 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   An application-
edc0: 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c  supplied.** impl
edd0: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
ede0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
edf0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
ee00: 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75  d().** must retu
ee10: 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
ee20: 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f  n success and so
ee30: 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20  me other [error 
ee40: 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61  code] upon.** fa
ee50: 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ilure..*/.int sq
ee60: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ee70: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
ee80: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69  te3_shutdown(voi
ee90: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
eea0: 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69  os_init(void);.i
eeb0: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nt sqlite3_os_en
eec0: 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d(void);../*.** 
eed0: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
eee0: 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65  uring The SQLite
eef0: 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54   Library.**.** T
ef00: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
ef10: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
ef20: 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c   used to make gl
ef30: 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  obal configurati
ef40: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
ef50: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
ef60: 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20   to tune SQLite 
ef70: 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
ef80: 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20  needs of.** the 
ef90: 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68  application.  Th
efa0: 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  e default config
efb0: 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d  uration is recom
efc0: 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a  mended for most.
efd0: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
efe0: 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74  and so this rout
eff0: 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e  ine is usually n
f000: 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49  ot necessary.  I
f010: 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64  t is.** provided
f020: 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65   to support rare
f030: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69   applications wi
f040: 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73  th unusual needs
f050: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
f060: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
f070: 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68  erface is not th
f080: 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61  readsafe.  The a
f090: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75  pplication.** mu
f0a0: 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e  st insure that n
f0b0: 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
f0c0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e  nterfaces are in
f0d0: 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a  voked by other.*
f0e0: 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20  * threads while 
f0f0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
f100: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75   is running.  Fu
f110: 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74  rthermore, sqlit
f120: 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d  e3_config().** m
f130: 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b  ay only be invok
f140: 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72  ed prior to libr
f150: 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ary initializati
f160: 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
f170: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f180: 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74  )] or after shut
f190: 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33  down by [sqlite3
f1a0: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a  _shutdown()]..**
f1b0: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e   ^If sqlite3_con
f1c0: 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20  fig() is called 
f1d0: 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69  after [sqlite3_i
f1e0: 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64  nitialize()] and
f1f0: 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69   before.** [sqli
f200: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
f210: 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74  then it will ret
f220: 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  urn SQLITE_MISUS
f230: 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65  E..** Note, howe
f240: 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74  ver, that ^sqlit
f250: 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20  e3_config() can 
f260: 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72  be called as par
f270: 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  t of the.** impl
f280: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  ementation of an
f290: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
f2a0: 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73  ined [sqlite3_os
f2b0: 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _init()]..**.** 
f2c0: 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
f2d0: 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
f2e0: 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74  nfig() is an int
f2f0: 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75  eger.** [configu
f300: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74  ration option] t
f310: 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a  hat determines.*
f320: 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20  * what property 
f330: 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20  of SQLite is to 
f340: 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20  be configured.  
f350: 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
f360: 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70  ents.** vary dep
f370: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63  ending on the [c
f380: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
f390: 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
f3a0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
f3b0: 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e  *.** ^When a con
f3c0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
f3d0: 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65  n is set, sqlite
f3e0: 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  3_config() retur
f3f0: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
f400: 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f  ** ^If the optio
f410: 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20  n is unknown or 
f420: 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
f430: 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69   to set the opti
f440: 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  on.** then this 
f450: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
f460: 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  a non-zero [erro
f470: 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20  r code]..*/.int 
f480: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
f490: 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
f4a0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
f4b0: 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
f4c0: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  nnections.**.** 
f4d0: 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
f4e0: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
f4f0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
f500: 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
f510: 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
f520: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
f530: 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
f540: 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
f550: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
f560: 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
f570: 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
f580: 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
f590: 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
f5a0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
f5b0: 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
f5c0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a  irst argument)..
f5d0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
f5e0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
f5f0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44  ite3_db_config(D
f600: 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a  ,V,...)  is the.
f610: 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ** [SQLITE_DBCON
f620: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20  FIG_LOOKASIDE | 
f630: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
f640: 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72  rb] - an integer
f650: 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69   code .** that i
f660: 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73  ndicates what as
f670: 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74  pect of the [dat
f680: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
f690: 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69  ] is being confi
f6a0: 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71  gured..** Subseq
f6b0: 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76  uent arguments v
f6c0: 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
f6d0: 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
f6e0: 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e  on verb..**.** ^
f6f0: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
f700: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  _db_config() ret
f710: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
f720: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
f730: 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73  the call is cons
f740: 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75  idered successfu
f750: 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
f760: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69  3_db_config(sqli
f770: 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e  te3*, int op, ..
f780: 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
f790: 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
f7a0: 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a  cation Routines.
f7b0: 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
f7c0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
f7d0: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
f7e0: 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53  erface between S
f7f0: 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77  QLite.** and low
f800: 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
f810: 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
f820: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62  s..**.** This ob
f830: 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20  ject is used in 
f840: 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69  only one place i
f850: 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74  n the SQLite int
f860: 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69  erface..** A poi
f870: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
f880: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
f890: 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  ct is the argume
f8a0: 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  nt to.** [sqlite
f8b0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e  3_config()] when
f8c0: 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
f8d0: 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  on option is.** 
f8e0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
f8f0: 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54  ALLOC] or [SQLIT
f900: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
f910: 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65  OC].  .** By cre
f920: 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63  ating an instanc
f930: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
f940: 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20  .** and passing 
f950: 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
f960: 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
f970: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a  ONFIG_MALLOC]).*
f980: 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75  * during configu
f990: 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69  ration, an appli
f9a0: 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69  cation can speci
f9b0: 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
f9c0: 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
f9d0: 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
f9e0: 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75   for SQLite to u
f9f0: 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
fa00: 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d  s.** dynamic mem
fa10: 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ory needs..**.**
fa20: 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74   Note that SQLit
fa30: 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76  e comes with sev
fa40: 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d  eral [built-in m
fa50: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
fa60: 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65  ].** that are pe
fa70: 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65  rfectly adequate
fa80: 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65   for the overwhe
fa90: 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f  lming majority o
faa0: 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
fab0: 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  * and that this 
fac0: 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75  object is only u
fad0: 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20  seful to a tiny 
fae0: 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  minority of appl
faf0: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  ications.** with
fb00: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d   specialized mem
fb10: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
fb20: 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68  equirements.  Th
fb30: 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20  is object is.** 
fb40: 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67  also used during
fb50: 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69   testing of SQLi
fb60: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73  te in order to s
fb70: 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
fb80: 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
fb90: 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73  allocator that s
fba0: 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20  imulates memory 
fbb0: 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f  out-of-memory co
fbc0: 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f  nditions in.** o
fbd0: 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74  rder to verify t
fbe0: 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76  hat SQLite recov
fbf0: 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66  ers gracefully f
fc00: 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64  rom such.** cond
fc10: 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  itions..**.** Th
fc20: 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c  e xMalloc, xReal
fc30: 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d  loc, and xFree m
fc40: 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b  ethods must work
fc50: 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c   like the.** mal
fc60: 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29  loc(), realloc()
fc70: 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63   and free() func
fc80: 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73  tions from the s
fc90: 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
fca0: 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  y..** ^SQLite gu
fcb0: 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
fcc0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
fcd0: 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63  t to.** xRealloc
fce0: 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c   is always a val
fcf0: 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61  ue returned by a
fd00: 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78   prior call to x
fd10: 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78  Roundup..**.** x
fd20: 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
fd30: 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
fd40: 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
fd50: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
fd60: 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
fd70: 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
fd80: 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
fd90: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
fda0: 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
fdb0: 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
fdc0: 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
fdd0: 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
fde0: 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
fdf0: 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
fe00: 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
fe10: 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
fe20: 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
fe30: 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
fe40: 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
fe50: 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
fe60: 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
fe70: 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
fe80: 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
fe90: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
fea0: 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
feb0: 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
fec0: 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
fed0: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
fee0: 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
fef0: 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
ff00: 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
ff10: 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
ff20: 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
ff30: 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
ff40: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
ff50: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
ff60: 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
ff70: 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
ff80: 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
ff90: 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
ffa0: 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
ffb0: 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
ffc0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
ffd0: 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
ffe0: 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
fff0: 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
10000 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
10010 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (For example,.**
10020 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61   it might alloca
10030 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d  te any require m
10040 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61  utexes or initia
10050 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61  lize internal da
10060 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73  ta.** structures
10070 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e  .  The xShutdown
10080 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
10090 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20  ed (indirectly) 
100a0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  by.** [sqlite3_s
100b0 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73  hutdown()] and s
100c0 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65  hould deallocate
100d0 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61   any resources a
100e0 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49  cquired.** by xI
100f0 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61  nit.  The pAppDa
10100 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73  ta pointer is us
10110 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  ed as the only p
10120 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78  arameter to.** x
10130 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f  Init and xShutdo
10140 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  wn..**.** SQLite
10150 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
10160 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
10170 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68  MASTER] mutex wh
10180 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a  en it invokes.**
10190 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
101a0 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20  d, so the xInit 
101b0 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20  method need not 
101c0 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  be threadsafe.  
101d0 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e  The.** xShutdown
101e0 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20   method is only 
101f0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c  called from [sql
10200 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
10210 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e   so it does.** n
10220 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68  ot need to be th
10230 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e  readsafe either.
10240 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20    For all other 
10250 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a  methods, SQLite.
10260 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  ** holds the [SQ
10270 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
10280 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20  C_MEM] mutex as 
10290 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b  long as the.** [
102a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
102b0 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75  MSTATUS] configu
102c0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
102d0 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63   turned on (whic
102e0 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65  h.** it is by de
102f0 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68  fault) and so th
10300 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75  e methods are au
10310 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69  tomatically seri
10320 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76  alized..** Howev
10330 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43  er, if [SQLITE_C
10340 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
10350 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68   is disabled, th
10360 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  en the other.** 
10370 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20  methods must be 
10380 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c  threadsafe or el
10390 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77  se make their ow
103a0 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66  n arrangements f
103b0 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74  or.** serializat
103c0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ion..**.** SQLit
103d0 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76  e will never inv
103e0 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65  oke xInit() more
103f0 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f   than once witho
10400 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e  ut an intervenin
10410 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68  g.** call to xSh
10420 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70  utdown()..*/.typ
10430 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
10440 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
10450 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
10460 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
10470 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
10480 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c  {.  void *(*xMal
10490 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20  loc)(int);      
104a0 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c     /* Memory all
104b0 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  ocation function
104c0 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72   */.  void (*xFr
104d0 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ee)(void*);     
104e0 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70       /* Free a p
104f0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
10500 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65  */.  void *(*xRe
10510 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74  alloc)(void*,int
10520 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e  );  /* Resize an
10530 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
10540 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f   int (*xSize)(vo
10550 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
10560 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69  /* Return the si
10570 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74  ze of an allocat
10580 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
10590 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20  Roundup)(int);  
105a0 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64          /* Round
105b0 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65   up request size
105c0 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73   to allocation s
105d0 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ize */.  int (*x
105e0 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20  Init)(void*);   
105f0 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69          /* Initi
10600 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
10610 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
10620 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e  void (*xShutdown
10630 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f  )(void*);      /
10640 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74  * Deinitialize t
10650 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
10660 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tor */.  void *p
10670 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
10680 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d          /* Argum
10690 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61  ent to xInit() a
106a0 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a  nd xShutdown() *
106b0 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
106c0 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74  3REF: Configurat
106d0 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b  ion Options.** K
106e0 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67  EYWORDS: {config
106f0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a  uration option}.
10700 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
10710 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
10720 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
10730 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10740 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
10750 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
10760 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
10770 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
10780 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
10790 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
107a0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
107b0 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
107c0 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
107d0 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
107e0 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
107f0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10800 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
10810 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
10820 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
10830 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
10840 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
10850 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
10860 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
10870 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
10880 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c  orked.  The [sql
10890 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
108a0 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
108b0 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
108c0 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
108d0 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
108e0 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
108f0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
10900 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
10910 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
10920 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
10930 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
10940 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
10950 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
10960 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
10970 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
10980 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
10990 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
109a0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
109b0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
109c0 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e  o Single-thread.
109d0 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
109e0 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
109f0 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e   all mutexing an
10a00 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e  d puts SQLite in
10a10 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20  to a mode where 
10a20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75  it can only be u
10a30 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67  sed.** by a sing
10a40 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66  le thread.   ^If
10a50 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
10a60 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
10a70 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
10a80 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
10a90 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
10aa0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
10ab0 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
10ac0 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e  possible to chan
10ad0 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ge the [threadin
10ae0 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73  g mode] from its
10af0 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75   default.** valu
10b00 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65  e of Single-thre
10b10 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74  ad and so [sqlit
10b20 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
10b30 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51  l return .** [SQ
10b40 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
10b50 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53  alled with the S
10b60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
10b70 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e  GLETHREAD.** con
10b80 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10b90 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
10ba0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
10bb0 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e  LTITHREAD]] <dt>
10bc0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
10bd0 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  LTITHREAD</dt>.*
10be0 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
10bf0 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
10c00 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
10c10 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
10c20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
10c30 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69  g mode] to Multi
10c40 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
10c50 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
10c60 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e  ables.** mutexin
10c70 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  g on [database c
10c80 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
10c90 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
10ca0 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
10cb0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
10cc0 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
10cd0 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61  or serializing a
10ce0 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74  ccess to.** [dat
10cf0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10d00 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
10d10 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42   statements].  B
10d20 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73  ut other mutexes
10d30 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
10d40 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  so that SQLite w
10d50 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75  ill be safe to u
10d60 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68  se in a multi-th
10d70 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f  readed.** enviro
10d80 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73  nment as long as
10d90 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20   no two threads 
10da0 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
10db0 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61  he same.** [data
10dc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
10dd0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
10de0 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  e.  ^If SQLite i
10df0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
10e00 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
10e10 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
10e20 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
10e30 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
10e40 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
10e50 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
10e60 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69  to set the Multi
10e70 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
10e80 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20  ng mode] and.** 
10e90 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
10ea0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  )] will return [
10eb0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
10ec0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
10ed0 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
10ee0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f  G_MULTITHREAD co
10ef0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10f00 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
10f10 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
10f20 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e  ERIALIZED]] <dt>
10f30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
10f40 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a  RIALIZED</dt>.**
10f50 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
10f60 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
10f70 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
10f80 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
10f90 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
10fa0 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c   mode] to Serial
10fb0 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77  ized. In other w
10fc0 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f  ords, this optio
10fd0 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c  n enables.** all
10fe0 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69   mutexes includi
10ff0 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65  ng the recursive
11000 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b  .** mutexes on [
11010 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11020 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
11030 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
11040 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69  jects..** In thi
11050 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73  s mode (which is
11060 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65   the default whe
11070 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
11080 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51  iled with.** [SQ
11090 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
110a0 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c  1]) the SQLite l
110b0 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65  ibrary will itse
110c0 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63  lf serialize acc
110d0 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62  ess.** to [datab
110e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
110f0 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
11100 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68  tatements] so th
11110 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63  at the.** applic
11120 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f  ation is free to
11130 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64   use the same [d
11140 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11150 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61  on] or the.** sa
11160 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
11170 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65  tement] in diffe
11180 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20  rent threads at 
11190 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a  the same time..*
111a0 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  * ^If SQLite is 
111b0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
111c0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
111d0 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
111e0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
111f0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
11200 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
11210 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
11220 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69   set the Seriali
11230 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
11240 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ode] and.** [sql
11250 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
11260 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
11270 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
11280 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
11290 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
112a0 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75  RIALIZED configu
112b0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
112c0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
112d0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
112e0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
112f0 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
11300 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
11310 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
11320 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
11330 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
11340 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
11350 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
11360 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
11370 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
11380 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
11390 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
113a0 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  ve low-level mem
113b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
113c0 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
113d0 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  ed in place of.*
113e0 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  * the memory all
113f0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
11400 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
11410 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61  te.)^ ^SQLite ma
11420 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70  kes.** its own p
11430 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
11440 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
11450 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
11460 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
11470 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20  e.** before the 
11480 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
11490 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  )] call returns.
114a0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
114b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
114c0 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
114d0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
114e0 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
114f0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
11500 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
11510 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
11520 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
11530 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
11540 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
11550 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
11560 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  re.  The [sqlite
11570 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a  3_mem_methods].*
11580 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
11590 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
115a0 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
115b0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
115c0 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  on routines.)^.*
115d0 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
115e0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
115f0 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
11600 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
11610 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
11620 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74  with a wrapper t
11630 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20  hat simulations 
11640 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
11650 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20  n failure or.** 
11660 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73  tracks memory us
11670 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  age, for example
11680 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
11690 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
116a0 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51  MSTATUS]] <dt>SQ
116b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
116c0 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  TATUS</dt>.** <d
116d0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
116e0 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67  takes single arg
116f0 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
11700 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  t, interpreted a
11710 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c  s a .** boolean,
11720 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f   which enables o
11730 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  r disables the c
11740 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d  ollection of mem
11750 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a  ory allocation .
11760 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e  ** statistics. ^
11770 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  (When memory all
11780 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
11790 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 2c  cs are disabled,
117a0 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69   the .** followi
117b0 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ng SQLite interf
117c0 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d  aces become non-
117d0 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20  operational:.** 
117e0 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e    <ul>.**   <li>
117f0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
11800 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c  _used()].**   <l
11810 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
11820 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a  ry_highwater()].
11830 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
11840 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
11850 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  it64()].**   <li
11860 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75  > [sqlite3_statu
11870 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29  s()].**   </ul>)
11880 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c  ^.** ^Memory all
11890 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
118a0 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62  cs are enabled b
118b0 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73  y default unless
118c0 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f   SQLite is.** co
118d0 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
118e0 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53  ITE_DEFAULT_MEMS
118f0 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63  TATUS]=0 in whic
11900 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a  h case memory.**
11910 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
11920 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62  istics are disab
11930 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
11940 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
11950 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
11960 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c  CRATCH]] <dt>SQL
11970 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
11980 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  CH</dt>.** <dd> 
11990 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
119a0 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
119b0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
119c0 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
119d0 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68  e for.** scratch
119e0 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20   memory.  There 
119f0 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
11a00 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20  nts:  A pointer 
11a10 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69  an 8-byte.** ali
11a20 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66  gned memory buff
11a30 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68  er from which th
11a40 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  e scratch alloca
11a50 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a  tions will be.**
11a60 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65   drawn, the size
11a70 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68   of each scratch
11a80 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29   allocation (sz)
11a90 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78  ,.** and the max
11aa0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73  imum number of s
11ab0 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
11ac0 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a  ns (N).  The sz.
11ad0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  ** argument must
11ae0 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f   be a multiple o
11af0 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72  f 16..** The fir
11b00 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
11b10 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
11b20 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   an 8-byte align
11b30 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20  ed buffer.** of 
11b40 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79  at least sz*N by
11b50 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a  tes of memory..*
11b60 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
11b70 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20  se no more than 
11b80 74 77 6f 20 73 63 72 61 74 63 68 20 62 75 66 66  two scratch buff
11b90 65 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 20  ers per thread. 
11ba0 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20   So.** N should 
11bb0 62 65 20 73 65 74 20 74 6f 20 74 77 69 63 65 20  be set to twice 
11bc0 74 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78  the expected max
11bd0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
11be0 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69  hreads..** ^SQLi
11bf0 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65  te will never re
11c00 71 75 69 72 65 20 61 20 73 63 72 61 74 63 68 20  quire a scratch 
11c10 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d  buffer that is m
11c20 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69  ore than 6.** ti
11c30 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  mes the database
11c40 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20   page size. ^If 
11c50 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65  SQLite needs nee
11c60 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  ds additional.**
11c70 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20   scratch memory 
11c80 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
11c90 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20  rovided by this 
11ca0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11cb0 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b  tion, then .** [
11cc0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
11cd0 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74  ] will be used t
11ce0 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d  o obtain the mem
11cf0 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e  ory needed.</dd>
11d00 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11d10 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
11d20 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
11d30 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f  NFIG_PAGECACHE</
11d40 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
11d50 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  s option specifi
11d60 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
11d70 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53  ry buffer that S
11d80 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
11d90 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  r.** the databas
11da0 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74  e page cache wit
11db0 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61  h the default pa
11dc0 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
11dd0 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68  ntation.  .** Th
11de0 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
11df0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
11e00 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63  sed if an applic
11e10 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67  ation-define pag
11e20 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65  e.** cache imple
11e30 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61  mentation is loa
11e40 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51  ded using the SQ
11e50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
11e60 48 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54  HE2 option..** T
11e70 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
11e80 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
11e90 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74   option: A point
11ea0 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69  er to 8-byte ali
11eb0 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  gned.** memory, 
11ec0 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
11ed0 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a   page buffer (sz
11ee0 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65  ), and the numbe
11ef0 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a  r of pages (N)..
11f00 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65  ** The sz argume
11f10 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65  nt should be the
11f20 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72   size of the lar
11f30 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61  gest database pa
11f40 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f  ge.** (a power o
11f50 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31  f two between 51
11f60 32 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75  2 and 32768) plu
11f70 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61  s a little extra
11f80 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67   for each.** pag
11f90 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20  e header.  ^The 
11fa0 70 61 67 65 20 68 65 61 64 65 72 20 73 69 7a 65  page header size
11fb0 20 69 73 20 32 30 20 74 6f 20 34 30 20 62 79 74   is 20 to 40 byt
11fc0 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a  es depending on.
11fd0 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63 68  ** the host arch
11fe0 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69  itecture.  ^It i
11ff0 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72  s harmless, apar
12000 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65  t from the waste
12010 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20  d memory,.** to 
12020 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65  make sz a little
12030 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65   too large.  The
12040 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65   first.** argume
12050 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20  nt should point 
12060 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  to an allocation
12070 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
12080 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
12090 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  y..** ^SQLite wi
120a0 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72  ll use the memor
120b0 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  y provided by th
120c0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
120d0 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a   to satisfy its.
120e0 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20  ** memory needs 
120f0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20  for the first N 
12100 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64  pages that it ad
12110 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49  ds to cache.  ^I
12120 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  f additional.** 
12130 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
12140 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f  y is needed beyo
12150 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
12160 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69  ded by this opti
12170 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  on, then.** SQLi
12180 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69  te goes to [sqli
12190 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f  te3_malloc()] fo
121a0 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c  r the additional
121b0 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a   storage space..
121c0 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69  ** The pointer i
121d0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
121e0 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20  ment must.** be 
121f0 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
12200 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72  byte boundary or
12210 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
12220 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a  vior of SQLite.*
12230 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  * will be undefi
12240 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ned.</dd>.**.** 
12250 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12260 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  HEAP]] <dt>SQLIT
12270 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64  E_CONFIG_HEAP</d
12280 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
12290 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
122a0 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
122b0 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
122c0 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
122d0 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
122e0 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61  dynamic memory a
122f0 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20  llocation needs 
12300 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f  beyond those pro
12310 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20  vided.** for by 
12320 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
12330 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c  CRATCH] and [SQL
12340 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
12350 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  ACHE]..** There 
12360 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
12370 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61  nts: An 8-byte a
12380 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74  ligned pointer t
12390 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  o the memory,.**
123a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
123b0 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f  ytes in the memo
123c0 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74  ry buffer, and t
123d0 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
123e0 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e  ation size..** ^
123f0 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69  If the first poi
12400 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
12410 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c   pointer) is NUL
12420 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72  L, then SQLite r
12430 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69  everts.** to usi
12440 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d  ng its default m
12450 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
12460 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c  (the system mall
12470 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74  oc() implementat
12480 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67  ion),.** undoing
12490 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63   any prior invoc
124a0 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45  ation of [SQLITE
124b0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e  _CONFIG_MALLOC].
124c0 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d    ^If the.** mem
124d0 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ory pointer is n
124e0 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68  ot NULL and eith
124f0 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  er [SQLITE_ENABL
12500 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a  E_MEMSYS3] or.**
12510 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
12520 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66  MEMSYS5] are def
12530 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61  ined, then the a
12540 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72  lternative memor
12550 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69  y.** allocator i
12560 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e  s engaged to han
12570 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74  dle all of SQLit
12580 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  es memory alloca
12590 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54  tion needs..** T
125a0 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72  he first pointer
125b0 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   (the memory poi
125c0 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c  nter) must be al
125d0 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
125e0 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f  te.** boundary o
125f0 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68  r subsequent beh
12600 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20  avior of SQLite 
12610 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65  will be undefine
12620 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75  d..** The minimu
12630 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
12640 65 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32  e is capped at 2
12650 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65  **12. Reasonable
12660 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74   values.** for t
12670 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
12680 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32  ation size are 2
12690 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38  **5 through 2**8
126a0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
126b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
126c0 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  EX]] <dt>SQLITE_
126d0 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74  CONFIG_MUTEX</dt
126e0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
126f0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
12700 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
12710 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
12720 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
12730 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
12740 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
12750 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
12760 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
12770 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e  cifies.** altern
12780 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
12790 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74  mutex routines t
127a0 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
127b0 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20  ce.** the mutex 
127c0 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
127d0 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e  nto SQLite.)^  ^
127e0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
127f0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f  opy of the.** co
12800 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71  ntent of the [sq
12810 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
12820 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62  ods] structure b
12830 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74  efore the call t
12840 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
12850 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e  nfig()] returns.
12860 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
12870 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
12880 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
12890 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
128a0 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
128b0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
128c0 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
128d0 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
128e0 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
128f0 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
12900 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
12910 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
12920 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
12930 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
12940 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  G_MUTEX configur
12950 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
12960 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
12970 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
12980 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12990 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d  CONFIG_GETMUTEX]
129a0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
129b0 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74  FIG_GETMUTEX</dt
129c0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
129d0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
129e0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
129f0 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
12a00 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
12a10 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
12a20 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
12a30 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
12a40 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
12a50 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a  mutex_methods].*
12a60 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
12a70 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
12a80 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
12a90 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e   mutex routines.
12aa0 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  )^.** This optio
12ab0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
12ac0 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
12ad0 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f  fault mutex allo
12ae0 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
12af0 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
12b00 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20  r used to track 
12b10 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20  mutex usage for 
12b20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70  performance.** p
12b30 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74  rofiling or test
12b40 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  ing, for example
12b50 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .   ^If SQLite i
12b60 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
12b70 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
12b80 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
12b90 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
12ba0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
12bb0 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65  tion then.** the
12bc0 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67   entire mutexing
12bd0 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d   subsystem is om
12be0 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62  itted from the b
12bf0 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63  uild and hence c
12c00 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
12c10 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
12c20 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
12c30 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f  NFIG_GETMUTEX co
12c40 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
12c50 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  on will.** retur
12c60 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
12c70 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
12c80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
12c90 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c  KASIDE]] <dt>SQL
12ca0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
12cb0 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
12cc0 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
12cd0 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
12ce0 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
12cf0 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a  ne the default.*
12d00 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
12d10 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b  ion for the look
12d20 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
12d30 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a  ocator on each.*
12d40 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
12d50 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69  ection].  The fi
12d60 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
12d70 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
12d80 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
12d90 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68  ffer slot and th
12da0 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20  e second is the 
12db0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
12dc0 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20  ts allocated to 
12dd0 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
12de0 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54  nnection.)^  ^(T
12df0 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
12e00 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c  the.** <i>defaul
12e10 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20  t</i> lookaside 
12e20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54  size. The [SQLIT
12e30 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
12e40 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f  SIDE].** verb to
12e50 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
12e60 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73  fig()] can be us
12e70 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  ed to change the
12e80 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f   lookaside.** co
12e90 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69  nfiguration on i
12ea0 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63  ndividual connec
12eb0 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a  tions.)^ </dd>.*
12ec0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12ed0 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c  NFIG_PCACHE2]] <
12ee0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12ef0 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a  _PCACHE2</dt>.**
12f00 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
12f10 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
12f20 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
12f30 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
12f40 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33  o.** an [sqlite3
12f50 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
12f60 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20  ] object.  This 
12f70 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73  object specifies
12f80 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
12f90 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61  * to a custom pa
12fa0 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
12fb0 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c  ntation.)^  ^SQL
12fc0 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
12fd0 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63   of the.** objec
12fe0 74 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f  t and uses it fo
12ff0 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  r page cache mem
13000 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
13010 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13020 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
13030 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c  CACHE2]] <dt>SQL
13040 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
13050 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHE2</dt>.** <d
13060 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
13070 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
13080 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
13090 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
130a0 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63  n.** [sqlite3_pc
130b0 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
130c0 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63  bject.  SQLite c
130d0 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72  opies of the cur
130e0 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63  rent.** page cac
130f0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
13100 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65  n into that obje
13110 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ct.)^ </dd>.**.*
13120 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13130 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49  G_LOG]] <dt>SQLI
13140 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64  TE_CONFIG_LOG</d
13150 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
13160 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
13170 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  G option takes t
13180 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20  wo arguments: a 
13190 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20  pointer to a.** 
131a0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
131b0 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f  call signature o
131c0 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  f void(*)(void*,
131d0 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  int,const char*)
131e0 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e  , .** and a poin
131f0 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66  ter to void. ^If
13200 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
13210 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
13220 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f  L, it is.** invo
13230 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ked by [sqlite3_
13240 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73  log()] to proces
13250 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65  s each logging e
13260 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
13270 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  * function point
13280 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20  er is NULL, the 
13290 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
132a0 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65  interface become
132b0 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54  s a no-op..** ^T
132c0 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20  he void pointer 
132d0 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f  that is the seco
132e0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53  nd argument to S
132f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
13300 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68   is.** passed th
13310 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
13320 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
13330 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
13340 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
13350 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65  * function whene
13360 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f  ver that functio
13370 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  n is invoked.  ^
13380 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
13390 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c  eter to.** the l
133a0 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69  ogger function i
133b0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
133c0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
133d0 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  to the correspon
133e0 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ding.** [sqlite3
133f0 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64  _log()] call and
13400 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
13410 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64  be a [result cod
13420 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74  e] or an.** [ext
13430 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
13440 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  e].  ^The third 
13450 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64  parameter passed
13460 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69   to the logger i
13470 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65  s.** log message
13480 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e   after formattin
13490 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73  g via [sqlite3_s
134a0 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54  nprintf()]..** T
134b0 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e  he SQLite loggin
134c0 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  g interface is n
134d0 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68  ot reentrant; th
134e0 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
134f0 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79  n.** supplied by
13500 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
13510 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65   must not invoke
13520 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
13530 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d  rface..** In a m
13540 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70  ulti-threaded ap
13550 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61  plication, the a
13560 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
13570 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
13580 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68  ction must be th
13590 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a  readsafe. </dd>.
135a0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
135b0 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e  ONFIG_URI]] <dt>
135c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
135d0 49 0a 2a 2a 20 3c 64 64 3e 20 54 68 69 73 20 6f  I.** <dd> This o
135e0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
135f0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
13600 20 74 79 70 65 20 69 6e 74 2e 20 49 66 20 6e 6f   type int. If no
13610 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a 2a 20  n-zero, then.** 
13620 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
13630 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64  globally enabled
13640 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74  . If the paramet
13650 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e  er is zero, then
13660 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a 2a 2a   URI handling.**
13670 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73   is globally dis
13680 61 62 6c 65 64 2e 20 49 66 20 55 52 49 20 68 61  abled. If URI ha
13690 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
136a0 6c 79 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20  ly enabled, all 
136b0 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70 61 73  filenames.** pas
136c0 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  sed to [sqlite3_
136d0 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
136e0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 5b 73  3_open_v2()], [s
136f0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
13700 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64   or.** specified
13710 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54   as part of [ATT
13720 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72  ACH] commands ar
13730 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
13740 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73   URIs, regardles
13750 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20  s.** of whether 
13760 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49  or not the [SQLI
13770 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
13780 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
13790 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
137a0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
137b0 65 64 2e 20 49 66 20 69 74 20 69 73 20 67 6c 6f  ed. If it is glo
137c0 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20  bally disabled, 
137d0 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a  filenames are.**
137e0 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65   only interprete
137f0 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65  d as URIs if the
13800 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49   SQLITE_OPEN_URI
13810 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
13820 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  n the.** databas
13830 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
13840 6f 70 65 6e 65 64 2e 20 42 79 20 64 65 66 61 75  opened. By defau
13850 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  lt, URI handling
13860 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20   is globally.** 
13870 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65  disabled. The de
13880 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20  fault value may 
13890 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f  be changed by co
138a0 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65  mpiling with the
138b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  .** [SQLITE_USE_
138c0 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69  URI] symbol defi
138d0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ned..**.** [[SQL
138e0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
138f0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d  ING_INDEX_SCAN]]
13900 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13910 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
13920 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 20 54  X_SCAN.** <dd> T
13930 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
13940 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65   a single intege
13950 72 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  r argument which
13960 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
13970 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e 20  as.** a boolean 
13980 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62  in order to enab
13990 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
139a0 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e  e use of coverin
139b0 67 20 69 6e 64 69 63 65 73 20 66 6f 72 0a 2a 2a  g indices for.**
139c0 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e   full table scan
139d0 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f  s in the query o
139e0 70 74 69 6d 69 7a 65 72 2e 20 20 54 68 65 20 64  ptimizer.  The d
139f0 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69  efault setting i
13a00 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20  s determined.** 
13a10 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41  by the [SQLITE_A
13a20 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  LLOW_COVERING_IN
13a30 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c  DEX_SCAN] compil
13a40 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f  e-time option, o
13a50 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20  r is "on".** if 
13a60 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  that compile-tim
13a70 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74  e option is omit
13a80 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c  ted..** The abil
13a90 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74  ity to disable t
13aa0 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69  he use of coveri
13ab0 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66  ng indices for f
13ac0 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a  ull table scans.
13ad0 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73 6f  ** is because so
13ae0 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63  me incorrectly c
13af0 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c  oded legacy appl
13b00 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d  ications might m
13b10 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 61  alfunction.** ma
13b20 6c 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 20 74  lfunction when t
13b30 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20  he optimization 
13b40 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f  is enabled.  Pro
13b50 76 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69  viding the abili
13b60 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65  ty to.** disable
13b70 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f   the optimizatio
13b80 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64  n allows the old
13b90 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63  er, buggy applic
13ba0 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f  ation code to wo
13bb0 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68  rk.** without ch
13bc0 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e  ange even with n
13bd0 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  ewer versions of
13be0 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b   SQLite..**.** [
13bf0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
13c00 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45  CACHE]] [[SQLITE
13c10 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
13c20 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  E]].** <dt>SQLIT
13c30 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
13c40 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  and SQLITE_CONFI
13c50 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c  G_GETPCACHE.** <
13c60 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e  dd> These option
13c70 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61  s are obsolete a
13c80 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  nd should not be
13c90 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64   used by new cod
13ca0 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72  e..** They are r
13cb0 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b  etained for back
13cc0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
13cd0 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20  ity but are now 
13ce0 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e  no-ops..** </dl>
13cf0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13d00 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a  CONFIG_SQLLOG]].
13d10 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
13d20 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c  NFIG_SQLLOG.** <
13d30 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  dd>This option i
13d40 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
13d50 20 69 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f   if sqlite is co
13d60 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
13d70 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  ** SQLITE_ENABLE
13d80 5f 53 51 4c 4c 4f 47 20 70 72 65 2d 70 72 6f 63  _SQLLOG pre-proc
13d90 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69  essor macro defi
13da0 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 61  ned. The first a
13db0 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a  rgument should.*
13dc0 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  * be a pointer t
13dd0 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20  o a function of 
13de0 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69  type void(*)(voi
13df0 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73  d*,sqlite3*,cons
13e00 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a  t char*, int)..*
13e10 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f  * The second sho
13e20 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20 28  uld be of type (
13e30 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c  void*). The call
13e40 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
13e50 62 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a  by the library.*
13e60 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70 61 72  * in three separ
13e70 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ate circumstance
13e80 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  s, identified by
13e90 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65   the value passe
13ea0 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72  d as the.** four
13eb0 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66  th parameter. If
13ec0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
13ed0 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e  meter is 0, then
13ee0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
13ef0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73  nnection.** pass
13f00 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
13f10 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75   argument has ju
13f20 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20  st been opened. 
13f30 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
13f40 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20  nt.** points to 
13f50 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e  a buffer contain
13f60 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  ing the name of 
13f70 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73  the main databas
13f80 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a  e file. If the.*
13f90 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  * fourth paramet
13fa0 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68  er is 1, then th
13fb0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
13fc0 74 68 61 74 20 74 68 65 20 74 68 69 72 64 20 70  that the third p
13fd0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e  arameter.** poin
13fe0 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62  ts to has just b
13ff0 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72  een executed. Or
14000 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74 68 20  , if the fourth 
14010 70 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20  parameter is 2, 
14020 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e  then.** the conn
14030 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73  ection being pas
14040 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
14050 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 62  d parameter is b
14060 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65  eing closed. The
14070 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65  .** third parame
14080 74 65 72 20 69 73 20 70 61 73 73 65 64 20 4e 55  ter is passed NU
14090 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e  LL In this case.
140a0 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
140b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
140c0 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
140d0 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   1  /* nil */.#d
140e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
140f0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
14100 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    2  /* nil */.#
14110 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
14120 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
14130 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     3  /* nil */.
14140 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
14150 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20  ONFIG_MALLOC    
14160 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65      4  /* sqlite
14170 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
14180 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
14190 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
141a0 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69  C     5  /* sqli
141b0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
141c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
141d0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
141e0 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f  H       6  /* vo
141f0 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
14200 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
14210 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
14220 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20  CACHE     7  /* 
14230 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
14240 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
14250 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
14260 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f  AP          8  /
14270 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79  * void*, int nBy
14280 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23  te, int min */.#
14290 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
142a0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20  NFIG_MEMSTATUS  
142b0 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e     9  /* boolean
142c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
142d0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
142e0 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71         10  /* sq
142f0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
14300 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
14310 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
14320 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f  TMUTEX     11  /
14330 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
14340 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70  methods* */./* p
14350 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45  reviously SQLITE
14360 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c  _CONFIG_CHUNKALL
14370 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e  OC 12 which is n
14380 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23  ow unused. */ .#
14390 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
143a0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
143b0 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74    13  /* int int
143c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
143d0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
143e0 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f         14  /* no
143f0 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  -op */.#define S
14400 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14410 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a  PCACHE    15  /*
14420 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e   no-op */.#defin
14430 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14440 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20  LOG          16 
14450 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a   /* xFunc, void*
14460 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
14470 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20  TE_CONFIG_URI   
14480 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e         17  /* in
14490 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
144a0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
144b0 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73  E2      18  /* s
144c0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
144d0 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69  thods2* */.#defi
144e0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
144f0 5f 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39  _GETPCACHE2   19
14500 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
14510 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f  che_methods2* */
14520 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14530 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
14540 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f  INDEX_SCAN 20  /
14550 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
14560 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
14570 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20  QLLOG       21  
14580 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64  /* xSqllog, void
14590 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  * */../*.** CAPI
145a0 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
145b0 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67  onnection Config
145c0 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
145d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
145e0 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
145f0 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
14600 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
14610 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
14620 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
14630 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
14640 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
14650 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
14660 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
14670 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
14680 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
14690 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
146a0 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
146b0 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
146c0 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
146d0 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
146e0 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
146f0 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
14700 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
14710 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
14720 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  m [sqlite3_db_co
14730 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
14740 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
14750 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e   call worked.  ^
14760 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  The [sqlite3_db_
14770 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
14780 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
14790 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
147a0 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
147b0 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
147c0 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
147d0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
147e0 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
147f0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
14800 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
14810 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
14820 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
14830 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65  ption takes thre
14840 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  e additional arg
14850 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
14860 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c  rmine the .** [l
14870 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
14880 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69  allocator] confi
14890 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  guration for the
148a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
148b0 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20  ction]..** ^The 
148c0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28  first argument (
148d0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
148e0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
148f0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20  db_config()] is 
14900 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
14910 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  a memory buffer 
14920 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61  to use for looka
14930 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  side memory..** 
14940 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
14950 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51  ent after the SQ
14960 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
14970 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20  OKASIDE verb.** 
14980 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77  may be NULL in w
14990 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65  hich case SQLite
149a0 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74   will allocate t
149b0 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20  he.** lookaside 
149c0 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73  buffer itself us
149d0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ing [sqlite3_mal
149e0 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63  loc()]. ^The sec
149f0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
14a00 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
14a10 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
14a20 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65  ffer slot.  ^The
14a30 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
14a40 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
14a50 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20  .** slots.  The 
14a60 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
14a70 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  er in the first 
14a80 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
14a90 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a   greater than.**
14aa0 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65   or equal to the
14ab0 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20   product of the 
14ac0 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64  second and third
14ad0 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65   arguments.  The
14ae0 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20   buffer.** must 
14af0 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
14b00 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8-byte boundary
14b10 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  .  ^If the secon
14b20 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
14b30 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
14b40 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f  _LOOKASIDE is no
14b50 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  t a multiple of 
14b60 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61  8, it is interna
14b70 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64  lly.** rounded d
14b80 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20  own to the next 
14b90 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65  smaller multiple
14ba0 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f   of 8.  ^(The lo
14bb0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a  okaside memory.*
14bc0 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
14bd0 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63  for a database c
14be0 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e  onnection can on
14bf0 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68  ly be changed wh
14c00 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65  en that.** conne
14c10 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72  ction is not cur
14c20 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f  rently using loo
14c30 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f  kaside memory, o
14c40 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  r in other words
14c50 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75  .** when the "cu
14c60 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74  rrent value" ret
14c70 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
14c80 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28  ite3_db_status](
14c90 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  D,[SQLITE_CONFIG
14ca0 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29  _LOOKASIDE],...)
14cb0 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79   is zero..** Any
14cc0 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e   attempt to chan
14cd0 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
14ce0 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72   memory configur
14cf0 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61  ation when looka
14d00 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69  side.** memory i
14d10 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20  s in use leaves 
14d20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
14d30 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20  n unchanged and 
14d40 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c  returns .** [SQL
14d50 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64  ITE_BUSY].)^</dd
14d60 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
14d70 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
14d80 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20  LE_FKEY</dt>.** 
14d90 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
14da0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
14db0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
14dc0 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  he enforcement o
14dd0 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65  f.** [foreign ke
14de0 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20  y constraints]. 
14df0 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
14e00 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
14e10 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
14e20 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
14e30 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
14e40 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
14e50 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
14e60 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ent,.** positive
14e70 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e   to enable FK en
14e80 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67  forcement or neg
14e90 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46  ative to leave F
14ea0 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a  K enforcement.**
14eb0 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
14ec0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
14ed0 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
14ee0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
14ef0 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
14f00 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
14f10 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
14f20 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
14f30 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20  is off or on.** 
14f40 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
14f50 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
14f60 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
14f70 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
14f80 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
14f90 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63  se the FK enforc
14fa0 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73  ement setting is
14fb0 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
14fc0 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
14fd0 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
14fe0 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
14ff0 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ER</dt>.** <dd> 
15000 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
15010 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
15020 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54  r disable [CREAT
15030 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
15040 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  gers]..** There 
15050 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
15060 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
15070 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
15080 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
15090 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
150a0 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72   0 to disable tr
150b0 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74  iggers,.** posit
150c0 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72  ive to enable tr
150d0 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69  iggers or negati
150e0 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
150f0 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65  setting unchange
15100 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  d..** The second
15110 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
15120 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
15130 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
15140 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
15150 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
15160 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65  e whether trigge
15170 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  rs are disabled 
15180 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f  or enabled.** fo
15190 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
151a0 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
151b0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
151c0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
151d0 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
151e0 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74   the trigger set
151f0 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
15200 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
15210 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  .**.** </dl>.*/.
15220 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
15230 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
15240 45 20 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a  E       1001  /*
15250 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a   void* int int *
15260 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15270 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
15280 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 20  _FKEY     1002  
15290 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
152a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
152b0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52  CONFIG_ENABLE_TR
152c0 49 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20  IGGER  1003  /* 
152d0 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a  int int* */.../*
152e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
152f0 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
15300 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
15310 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  Codes.**.** ^The
15320 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
15330 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
15340 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
15350 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
15360 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
15370 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
15380 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e  ure of SQLite. ^
15390 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
153a0 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65  ult.** codes are
153b0 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
153c0 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69  ault for histori
153d0 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  cal compatibilit
153e0 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  y..*/.int sqlite
153f0 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
15400 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a  t_codes(sqlite3*
15410 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
15420 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
15430 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64  ast Insert Rowid
15440 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74  .**.** ^Each ent
15450 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20  ry in an SQLite 
15460 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71  table has a uniq
15470 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
15480 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
15490 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
154a0 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
154b0 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
154c0 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
154d0 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
154e0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
154f0 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
15500 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
15510 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
15520 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
15530 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
15540 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
15550 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
15560 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
15570 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
15580 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
15590 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
155a0 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
155b0 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
155c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
155d0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
155e0 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
155f0 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73  most recent.** s
15600 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
15610 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  T] into the data
15620 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64  base from the [d
15630 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15640 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
15650 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e  rst argument.  ^
15660 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72  As of SQLite ver
15670 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 74 68 69 73  sion 3.7.7, this
15680 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 72 65 63   routines.** rec
15690 6f 72 64 73 20 74 68 65 20 6c 61 73 74 20 69 6e  ords the last in
156a0 73 65 72 74 20 72 6f 77 69 64 20 6f 66 20 62 6f  sert rowid of bo
156b0 74 68 20 6f 72 64 69 6e 61 72 79 20 74 61 62 6c  th ordinary tabl
156c0 65 73 20 61 6e 64 20 5b 76 69 72 74 75 61 6c 20  es and [virtual 
156d0 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20 5e 49 66 20  tables]..** ^If 
156e0 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  no successful [I
156f0 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20  NSERT]s.** have 
15700 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e  ever occurred on
15710 20 74 68 61 74 20 64 61 74 61 62 61 73 65 20 63   that database c
15720 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20  onnection, zero 
15730 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
15740 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45  ** ^(If an [INSE
15750 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69  RT] occurs withi
15760 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72 20 77  n a trigger or w
15770 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c  ithin a [virtual
15780 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f   table].** metho
15790 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75  d, then this rou
157a0 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  tine will return
157b0 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
157c0 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20  the inserted.** 
157d0 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  row as long as t
157e0 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
157f0 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68  rtual table meth
15800 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  od is running..*
15810 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74  * But once the t
15820 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61  rigger or virtua
15830 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65  l table method e
15840 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  nds, the value r
15850 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74  eturned .** by t
15860 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65  his routine reve
15870 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77  rts to what it w
15880 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72  as before the tr
15890 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
158a0 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64  .** table method
158b0 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20   began.)^.**.** 
158c0 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61  ^An [INSERT] tha
158d0 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61  t fails due to a
158e0 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
158f0 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a  ation is not a.*
15900 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
15910 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e  SERT] and does n
15920 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
15930 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
15940 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e  this.** routine.
15950 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f    ^Thus INSERT O
15960 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f  R FAIL, INSERT O
15970 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54  R IGNORE, INSERT
15980 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a   OR ROLLBACK,.**
15990 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41   and INSERT OR A
159a0 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61  BORT make no cha
159b0 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75  nges to the retu
159c0 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
159d0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e  .** routine when
159e0 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e   their insertion
159f0 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20   fails.  ^(When 
15a00 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
15a10 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20  E.** encounters 
15a20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
15a30 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20  lation, it does 
15a40 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a  not fail.  The.*
15a50 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75  * INSERT continu
15a60 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  es to completion
15a70 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20   after deleting 
15a80 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64  rows that caused
15a90 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69  .** the constrai
15aa0 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e  nt problem so IN
15ab0 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20  SERT OR REPLACE 
15ac0 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e  will always chan
15ad0 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e  ge.** the return
15ae0 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69   value of this i
15af0 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a  nterface.)^.**.*
15b00 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f  * ^For the purpo
15b10 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ses of this rout
15b20 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ine, an [INSERT]
15b30 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74   is considered t
15b40 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66  o.** be successf
15b50 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  ul even if it is
15b60 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f   subsequently ro
15b70 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
15b80 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   This function i
15b90 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20  s accessible to 
15ba0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76  SQL statements v
15bb0 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f  ia the.** [last_
15bc0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53  insert_rowid() S
15bd0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
15be0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
15bf0 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d  e thread perform
15c00 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d  s a new [INSERT]
15c10 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   on the same.** 
15c20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15c30 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73  ion while the [s
15c40 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
15c50 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66  rt_rowid()].** f
15c60 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
15c70 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e  ng and thus chan
15c80 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73  ges the last ins
15c90 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20  ert [rowid],.** 
15ca0 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
15cb0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
15cc0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
15cd0 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75  rowid()] is.** u
15ce0 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
15cf0 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c   might not equal
15d00 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20   either the old 
15d10 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61  or the new.** la
15d20 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
15d30 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  ]..*/.sqlite3_in
15d40 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  t64 sqlite3_last
15d50 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71  _insert_rowid(sq
15d60 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
15d70 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20  CAPI3REF: Count 
15d80 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  The Number Of Ro
15d90 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a  ws Modified.**.*
15da0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
15db0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
15dc0 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20  ber of database 
15dd0 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63  rows that were c
15de0 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73  hanged.** or ins
15df0 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
15e00 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
15e10 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
15e20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL statement.**
15e30 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   on the [databas
15e40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
15e50 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ecified by the f
15e60 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  irst parameter..
15e70 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65  ** ^(Only change
15e80 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63  s that are direc
15e90 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79  tly specified by
15ea0 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b   the [INSERT], [
15eb0 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  UPDATE],.** or [
15ec0 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e  DELETE] statemen
15ed0 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20  t are counted.  
15ee0 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65  Auxiliary change
15ef0 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74  s caused by.** t
15f00 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 65  riggers or [fore
15f10 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
15f20 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
15f30 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b  .)^ Use the.** [
15f40 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
15f50 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f  anges()] functio
15f60 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f  n to find the to
15f70 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  tal number of ch
15f80 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69  anges.** includi
15f90 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ng changes cause
15fa0 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61 6e  d by triggers an
15fb0 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63  d foreign key ac
15fc0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68  tions..**.** ^Ch
15fd0 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20  anges to a view 
15fe0 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74  that are simulat
15ff0 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41  ed by an [INSTEA
16000 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a  D OF trigger].**
16010 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
16020 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62  .  Only real tab
16030 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63  le changes are c
16040 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ounted..**.** ^(
16050 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69  A "row change" i
16060 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20  s a change to a 
16070 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20  single row of a 
16080 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20  single table.** 
16090 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53  caused by an INS
160a0 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20  ERT, DELETE, or 
160b0 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74  UPDATE statement
160c0 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20  .  Rows that.** 
160d0 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73  are changed as s
160e0 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b  ide effects of [
160f0 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
16100 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a  int resolution,.
16110 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f  ** rollback, ABO
16120 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b  RT processing, [
16130 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20  DROP TABLE], or 
16140 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  by any other.** 
16150 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f  mechanisms do no
16160 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63  t count as direc
16170 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e  t row changes.)^
16180 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65  .**.** A "trigge
16190 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20  r context" is a 
161a0 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69  scope of executi
161b0 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61  on that begins a
161c0 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20  nd.** ends with 
161d0 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20  the script of a 
161e0 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
161f0 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20  | trigger]. .** 
16200 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  Most SQL stateme
16210 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75  nts are.** evalu
16220 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20  ated outside of 
16230 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68  any trigger.  Th
16240 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c  is is the "top l
16250 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72  evel".** trigger
16260 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20   context.  If a 
16270 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72  trigger fires fr
16280 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  om the top level
16290 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67  , a.** new trigg
162a0 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e  er context is en
162b0 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75  tered for the du
162c0 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f  ration of that o
162d0 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20  ne.** trigger.  
162e0 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61  Subtriggers crea
162f0 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66  te subcontexts f
16300 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f  or their duratio
16310 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  n..**.** ^Callin
16320 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  g [sqlite3_exec(
16330 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73  )] or [sqlite3_s
16340 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65  tep()] recursive
16350 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63  ly does.** not c
16360 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67  reate a new trig
16370 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  ger context..**.
16380 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
16390 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
163a0 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 72  mber of direct r
163b0 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ow changes in th
163c0 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74  e.** most recent
163d0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
163e0 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
163f0 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
16400 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20  same.** trigger 
16410 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e  context..**.** ^
16420 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65  Thus, when calle
16430 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  d from the top l
16440 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74  evel, this funct
16450 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ion returns the.
16460 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  ** number of cha
16470 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
16480 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
16490 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
164a0 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f  E.** that also o
164b0 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20 74  ccurred at the t
164c0 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74  op level.  ^(Wit
164d0 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20  hin the body of 
164e0 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68  a trigger,.** th
164f0 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
16500 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  s() interface ca
16510 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66  n be called to f
16520 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
16530 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20  f.** changes in 
16540 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
16550 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45  y completed INSE
16560 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
16570 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65  ELETE.** stateme
16580 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f  nt within the bo
16590 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74  dy of the same t
165a0 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76  rigger..** Howev
165b0 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72  er, the number r
165c0 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74  eturned does not
165d0 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73   include changes
165e0 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75  .** caused by su
165f0 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20  btriggers since 
16600 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 72  those have their
16610 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a   own context.)^.
16620 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
16630 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
16640 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  l_changes()] int
16650 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b  erface, the.** [
16660 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
16670 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b  agma], and the [
16680 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
16690 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
166a0 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
166b0 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
166c0 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
166d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
166e0 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
166f0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
16700 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
16710 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
16720 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63  d.** is unpredic
16730 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
16740 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  aningful..*/.int
16750 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
16760 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
16770 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74  ** CAPI3REF: Tot
16780 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  al Number Of Row
16790 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a  s Modified.**.**
167a0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
167b0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
167c0 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65  er of row change
167d0 73 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53  s caused by [INS
167e0 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45  ERT],.** [UPDATE
167f0 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  ] or [DELETE] st
16800 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74  atements since t
16810 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
16820 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65  nection] was ope
16830 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f  ned..** ^(The co
16840 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  unt returned by 
16850 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
16860 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65 73  anges() includes
16870 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20   all changes.** 
16880 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45  from all [CREATE
16890 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
168a0 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e 64  er] contexts and
168b0 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79   changes made by
168c0 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
168d0 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76   actions]. Howev
168e0 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74  er,.** the count
168f0 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
16900 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74  e changes used t
16910 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50  o implement [REP
16920 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74  LACE] constraint
16930 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63  s,.** do rollbac
16940 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63  ks or ABORT proc
16950 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50  essing, or [DROP
16960 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69   TABLE] processi
16970 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e  ng.  The.** coun
16980 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
16990 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73  de rows of views
169a0 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49   that fire an [I
169b0 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
169c0 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66  r],.** though if
169d0 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20   the INSTEAD OF 
169e0 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68  trigger makes ch
169f0 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e  anges of its own
16a00 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20  , those changes 
16a10 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  .** are counted.
16a20 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  )^.** ^The sqlit
16a30 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
16a40 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e  () function coun
16a50 74 73 20 74 68 65 20 63 68 61 6e 67 65 73 20 61  ts the changes a
16a60 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65  s soon as.** the
16a70 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
16a80 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f  makes them is co
16a90 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68  mpleted (when th
16aa0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  e statement hand
16ab0 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20  le.** is passed 
16ac0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
16ad0 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
16ae0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a  _finalize()])..*
16af0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
16b00 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
16b10 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
16b20 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
16b30 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
16b40 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63  and the [total_c
16b50 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
16b60 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
16b70 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
16b80 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
16b90 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
16ba0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16bb0 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
16bc0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
16bd0 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
16be0 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  hen the value.**
16bf0 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70   returned is unp
16c00 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
16c10 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
16c20 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f  /.int sqlite3_to
16c30 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  tal_changes(sqli
16c40 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
16c50 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70  PI3REF: Interrup
16c60 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67  t A Long-Running
16c70 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68   Query.**.** ^Th
16c80 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  is function caus
16c90 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64  es any pending d
16ca0 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
16cb0 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a  n to abort and.*
16cc0 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20  * return at its 
16cd0 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75  earliest opportu
16ce0 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69  nity. This routi
16cf0 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a  ne is typically.
16d00 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73  ** called in res
16d10 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20  ponse to a user 
16d20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70  action such as p
16d30 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22  ressing "Cancel"
16d40 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68  .** or Ctrl-C wh
16d50 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e  ere the user wan
16d60 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20  ts a long query 
16d70 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c  operation to hal
16d80 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79  t.** immediately
16d90 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73  ..**.** ^It is s
16da0 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
16db0 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20   routine from a 
16dc0 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74  thread different
16dd0 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72   from the.** thr
16de0 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72  ead that is curr
16df0 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68  ently running th
16e00 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  e database opera
16e10 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a  tion.  But it.**
16e20 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
16e30 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
16e40 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  e with a [databa
16e50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
16e60 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64  hat.** is closed
16e70 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20   or might close 
16e80 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69  before sqlite3_i
16e90 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72  nterrupt() retur
16ea0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ns..**.** ^If an
16eb0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
16ec0 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69  s very nearly fi
16ed0 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69  nished at the ti
16ee0 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  me when.** sqlit
16ef0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69  e3_interrupt() i
16f00 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69  s called, then i
16f10 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65  t might not have
16f20 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a   an opportunity.
16f30 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75  ** to be interru
16f40 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63  pted and might c
16f50 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c  ontinue to compl
16f60 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  etion..**.** ^An
16f70 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74   SQL operation t
16f80 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74  hat is interrupt
16f90 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ed will return [
16fa0 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
16fb0 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e  ]..** ^If the in
16fc0 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70  terrupted SQL op
16fd0 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e  eration is an IN
16fe0 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
16ff0 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
17000 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70  is inside an exp
17010 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
17020 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69  n, then the enti
17030 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a  re transaction.*
17040 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64  * will be rolled
17050 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
17060 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  lly..**.** ^The 
17070 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
17080 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20  t(D) call is in 
17090 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c  effect until all
170a0 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
170b0 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
170c0 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  ents on [databas
170d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
170e0 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20  complete.  ^Any 
170f0 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  new SQL statemen
17100 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
17110 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
17120 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
17130 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65  pt() call and be
17140 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e  fore the .** run
17150 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20  ning statements 
17160 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
17170 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20   interrupted as 
17180 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e  if they had been
17190 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f  .** running prio
171a0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
171b0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
171c0 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61  l.  ^New SQL sta
171d0 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
171e0 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
171f0 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74  r the running st
17200 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65  atement count re
17210 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a  aches zero are.*
17220 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62  * not effected b
17230 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  y the sqlite3_in
17240 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41  terrupt()..** ^A
17250 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
17260 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68  _interrupt(D) th
17270 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74  at occurs when t
17280 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e  here are no runn
17290 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
172a0 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70  ments is a no-op
172b0 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65   and has no effe
172c0 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d  ct on SQL statem
172d0 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
172e0 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
172f0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
17300 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75  rupt() call retu
17310 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  rns..**.** If th
17320 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
17330 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69  ction closes whi
17340 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  le [sqlite3_inte
17350 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72  rrupt()].** is r
17360 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20  unning then bad 
17370 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65  things will like
17380 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f  ly happen..*/.vo
17390 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  id sqlite3_inter
173a0 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rupt(sqlite3*);.
173b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
173c0 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
173d0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49   SQL Statement I
173e0 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a  s Complete.**.**
173f0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
17400 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e  are useful durin
17410 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69  g command-line i
17420 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e  nput to determin
17430 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72  e if the.** curr
17440 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65  ently entered te
17450 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d  xt seems to form
17460 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
17470 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20  statement or.** 
17480 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  if additional in
17490 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65  put is needed be
174a0 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65  fore sending the
174b0 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51   text into.** SQ
174c0 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67  Lite for parsing
174d0 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
174e0 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74  es return 1 if t
174f0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a  he input string.
17500 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65  ** appears to be
17510 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
17520 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73  statement.  ^A s
17530 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67  tatement is judg
17540 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ed to be.** comp
17550 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20  lete if it ends 
17560 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e  with a semicolon
17570 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f   token and is no
17580 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a  t a prefix of a.
17590 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43  ** well-formed C
175a0 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74  REATE TRIGGER st
175b0 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63  atement.  ^Semic
175c0 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65  olons that are e
175d0 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a  mbedded within.*
175e0 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  * string literal
175f0 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e  s or quoted iden
17600 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20  tifier names or 
17610 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74  comments are not
17620 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20  .** independent 
17630 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65  tokens (they are
17640 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b   part of the tok
17650 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79  en in which they
17660 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64   are.** embedded
17670 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f  ) and thus do no
17680 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61  t count as a sta
17690 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f  tement terminato
176a0 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a  r.  ^Whitespace.
176b0 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20  ** and comments 
176c0 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20  that follow the 
176d0 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20  final semicolon 
176e0 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  are ignored..**.
176f0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
17700 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74  es return 0 if t
17710 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
17720 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66  incomplete.  ^If
17730 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c   a.** memory all
17740 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74  ocation fails, t
17750 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  hen SQLITE_NOMEM
17760 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
17770 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
17780 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65  nes do not parse
17790 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
177a0 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c  nts thus.** will
177b0 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74   not detect synt
177c0 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72  actically incorr
177d0 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  ect SQL..**.** ^
177e0 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e  (If SQLite has n
177f0 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69  ot been initiali
17800 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  zed using [sqlit
17810 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
17820 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e   prior .** to in
17830 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  voking sqlite3_c
17840 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e  omplete16() then
17850 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
17860 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
17870 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
17880 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d  y by sqlite3_com
17890 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74  plete16().  If t
178a0 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  hat initializati
178b0 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65  on fails,.** the
178c0 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
178d0 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
178e0 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c  complete16() wil
178f0 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a  l be non-zero.**
17900 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
17910 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
17920 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63  e input SQL is c
17930 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a  omplete.)^.**.**
17940 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
17950 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
17960 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
17970 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
17980 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a  UTF-8 string..**
17990 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
179a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
179b0 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20  te16()] must be 
179c0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
179d0 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
179e0 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
179f0 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20  e order..*/.int 
17a00 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
17a10 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  (const char *sql
17a20 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
17a30 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20  omplete16(const 
17a40 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a  void *sql);../*.
17a50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
17a60 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b  ister A Callback
17a70 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54   To Handle SQLIT
17a80 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a  E_BUSY Errors.**
17a90 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
17aa0 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63  e sets a callbac
17ab0 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  k function that 
17ac0 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
17ad0 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20   whenever.** an 
17ae0 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20  attempt is made 
17af0 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61  to open a databa
17b00 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e  se table that an
17b10 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20  other thread.** 
17b20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c  or process has l
17b30 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  ocked..**.** ^If
17b40 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
17b50 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ck is NULL, then
17b60 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
17b70 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
17b80 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72  BLOCKED].** is r
17b90 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
17ba0 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74  ely upon encount
17bb0 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20  ering the lock. 
17bc0 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
17bd0 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74  llback.** is not
17be0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
17bf0 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62  callback might b
17c00 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
17c10 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  wo arguments..**
17c20 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
17c30 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62  rgument to the b
17c40 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61  usy handler is a
17c50 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
17c60 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  d* pointer which
17c70 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64  .** is the third
17c80 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
17c90 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
17ca0 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  r().  ^The secon
17cb0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
17cc0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
17cd0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
17ce0 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65  e number of time
17cf0 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20  s that the busy 
17d00 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62  handler has.** b
17d10 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20  een invoked for 
17d20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65  this locking eve
17d30 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  nt.  ^If the.** 
17d40 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65  busy callback re
17d50 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f  turns 0, then no
17d60 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65   additional atte
17d70 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f  mpts are made to
17d80 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64  .** access the d
17d90 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c  atabase and [SQL
17da0 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
17db0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
17dc0 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ED] is returned.
17dd0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c  .** ^If the call
17de0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
17df0 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74  -zero, then anot
17e00 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69  her attempt.** i
17e10 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74  s made to open t
17e20 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20  he database for 
17e30 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20  reading and the 
17e40 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a  cycle repeats..*
17e50 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63  *.** The presenc
17e60 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64  e of a busy hand
17e70 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61  ler does not gua
17e80 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77  rantee that it w
17e90 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a  ill be invoked.*
17ea0 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20  * when there is 
17eb0 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e  lock contention.
17ec0 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65   ^If SQLite dete
17ed0 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f  rmines that invo
17ee0 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a  king the busy.**
17ef0 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72   handler could r
17f00 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c  esult in a deadl
17f10 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20  ock, it will go 
17f20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e  ahead and return
17f30 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
17f40 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  * or [SQLITE_IOE
17f50 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74  RR_BLOCKED] inst
17f60 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20  ead of invoking 
17f70 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
17f80 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20  ..** Consider a 
17f90 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f  scenario where o
17fa0 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  ne process is ho
17fb0 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63  lding a read loc
17fc0 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20  k that.** it is 
17fd0 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74  trying to promot
17fe0 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20  e to a reserved 
17ff0 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65  lock and.** a se
18000 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20  cond process is 
18010 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76  holding a reserv
18020 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20  ed lock that it 
18030 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20  is trying.** to 
18040 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78  promote to an ex
18050 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54  clusive lock.  T
18060 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
18070 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a   cannot proceed.
18080 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ** because it is
18090 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
180a0 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73  second and the s
180b0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61  econd process ca
180c0 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20  nnot.** proceed 
180d0 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
180e0 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72  ocked by the fir
180f0 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f  st.  If both pro
18100 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65  cesses.** invoke
18110 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
18120 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c  rs, neither will
18130 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65   make any progre
18140 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a  ss.  Therefore,.
18150 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e  ** SQLite return
18160 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  s [SQLITE_BUSY] 
18170 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72  for the first pr
18180 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68  ocess, hoping th
18190 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20  at this.** will 
181a0 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74  induce the first
181b0 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65   process to rele
181c0 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63  ase its read loc
181d0 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74  k and allow.** t
181e0 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
181f0 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a  s to proceed..**
18200 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
18210 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
18220 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s NULL..**.** ^T
18230 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  he [SQLITE_BUSY]
18240 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72   error is conver
18250 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49  ted to [SQLITE_I
18260 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a  OERR_BLOCKED].**
18270 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
18280 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66  in the middle of
18290 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63   a large transac
182a0 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74  tion where all t
182b0 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69  he.** changes wi
182c0 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20  ll not fit into 
182d0 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61  the in-memory ca
182e0 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  che.  SQLite wil
182f0 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c  l.** already hol
18300 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63  d a RESERVED loc
18310 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  k on the databas
18320 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e  e file, but it n
18330 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  eeds.** to promo
18340 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20  te this lock to 
18350 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61  EXCLUSIVE so tha
18360 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63  t it can spill c
18370 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e  ache.** pages in
18380 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
18390 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72  file without har
183a0 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a  m to concurrent.
183b0 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e 49 66  ** readers.  ^If
183c0 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
183d0 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63   promote the loc
183e0 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d  k, then the in-m
183f0 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77  emory.** cache w
18400 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61  ill be left in a
18410 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73  n inconsistent s
18420 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20  tate and so the 
18430 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73  error.** code is
18440 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74   promoted from t
18450 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65  he relatively be
18460 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  nign [SQLITE_BUS
18470 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72  Y] to.** the mor
18480 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45  e severe [SQLITE
18490 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
184a0 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20 63 6f    ^This error co
184b0 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20  de promotion.** 
184c0 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61  forces an automa
184d0 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20  tic rollback of 
184e0 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65  the changes.  Se
184f0 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  e the.** <a href
18500 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f  ="/cvstrac/wiki?
18510 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c  p=CorruptionFoll
18520 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e  owingBusyError">
18530 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f  .** CorruptionFo
18540 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
18550 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66  </a> wiki page f
18560 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20  or a discussion 
18570 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69  of why.** this i
18580 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a  s important..**.
18590 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
185a0 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
185b0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66  busy handler def
185c0 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a  ined for each.**
185d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
185e0 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67  ction].  Setting
185f0 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64   a new busy hand
18600 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a  ler clears any.*
18610 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74  * previously set
18620 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f   handler.)^  ^No
18630 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20  te that calling 
18640 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
18650 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c  meout()].** will
18660 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65   also set or cle
18670 61 72 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ar the busy hand
18680 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62  ler..**.** The b
18690 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  usy callback sho
186a0 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79  uld not take any
186b0 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d   actions which m
186c0 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74  odify the.** dat
186d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
186e0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
186f0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20  e busy handler. 
18700 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e   Any such action
18710 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75  s.** result in u
18720 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
18730 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79  r..** .** A busy
18740 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f   handler must no
18750 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  t close the data
18760 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
18770 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20  ** or [prepared 
18780 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
18790 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
187a0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74   handler..*/.int
187b0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
187c0 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
187d0 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  int(*)(void*,int
187e0 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
187f0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20  * CAPI3REF: Set 
18800 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a  A Busy Timeout.*
18810 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
18820 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74  ne sets a [sqlit
18830 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20  e3_busy_handler 
18840 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20  | busy handler] 
18850 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66  that sleeps.** f
18860 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61  or a specified a
18870 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68  mount of time wh
18880 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f  en a table is lo
18890 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64  cked.  ^The hand
188a0 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65  ler.** will slee
188b0 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  p multiple times
188c0 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20   until at least 
188d0 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
188e0 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a  s of sleeping.**
188f0 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65   have accumulate
18900 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65  d.  ^After at le
18910 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
18920 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
18930 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65  g,.** the handle
18940 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63  r returns 0 whic
18950 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65  h causes [sqlite
18960 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74  3_step()] to ret
18970 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  urn.** [SQLITE_B
18980 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
18990 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a  IOERR_BLOCKED]..
189a0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74  **.** ^Calling t
189b0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
189c0 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73   an argument les
189d0 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
189e0 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73  to zero.** turns
189f0 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61   off all busy ha
18a00 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ndlers..**.** ^(
18a10 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
18a20 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
18a30 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61  handler for a pa
18a40 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
18a50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18a60 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20  ] any any given 
18a70 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74  moment.  If anot
18a80 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
18a90 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20  .** was defined 
18aa0 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33   (using [sqlite3
18ab0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d  _busy_handler()]
18ac0 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  ) prior to calli
18ad0 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  ng.** this routi
18ae0 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62  ne, that other b
18af0 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63  usy handler is c
18b00 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69 6e 74  leared.)^.*/.int
18b10 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69   sqlite3_busy_ti
18b20 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20  meout(sqlite3*, 
18b30 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  int ms);../*.** 
18b40 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e  CAPI3REF: Conven
18b50 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46  ience Routines F
18b60 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69  or Running Queri
18b70 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  es.**.** This is
18b80 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66   a legacy interf
18b90 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65 73  ace that is pres
18ba0 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61  erved for backwa
18bb0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
18bc0 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69  y..** Use of thi
18bd0 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  s interface is n
18be0 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  ot recommended..
18bf0 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e  **.** Definition
18c00 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61  : A <b>result ta
18c10 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72  ble</b> is memor
18c20 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  y data structure
18c30 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a   created by the.
18c40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ** [sqlite3_get_
18c50 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61  table()] interfa
18c60 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61  ce.  A result ta
18c70 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a  ble records the.
18c80 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72  ** complete quer
18c90 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f  y results from o
18ca0 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69  ne or more queri
18cb0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  es..**.** The ta
18cc0 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79  ble conceptually
18cd0 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66   has a number of
18ce0 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e   rows and column
18cf0 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65  s.  But.** these
18d00 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74   numbers are not
18d10 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73   part of the res
18d20 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66  ult table itself
18d30 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62  .  These.** numb
18d40 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64  ers are obtained
18d50 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65   separately.  Le
18d60 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65  t N be the numbe
18d70 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64  r of rows.** and
18d80 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   M be the number
18d90 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a   of columns..**.
18da0 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
18db0 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  e is an array of
18dc0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72   pointers to zer
18dd0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
18de0 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54  -8 strings..** T
18df0 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d  here are (N+1)*M
18e00 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65   elements in the
18e10 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72   array.  The fir
18e20 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f  st M pointers po
18e30 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74  int.** to zero-t
18e40 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
18e50 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20  s that  contain 
18e60 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  the names of the
18e70 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65   columns..** The
18e80 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69   remaining entri
18e90 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20  es all point to 
18ea0 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20  query results.  
18eb0 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75  NULL values resu
18ec0 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f  lt.** in NULL po
18ed0 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68  inters.  All oth
18ee0 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e  er values are in
18ef0 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72   their UTF-8 zer
18f00 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
18f10 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74  string represent
18f20 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65  ation as returne
18f30 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
18f40 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a  lumn_text()]..**
18f50 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
18f60 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74  le might consist
18f70 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   of one or more 
18f80 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
18f90 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  ns..** It is not
18fa0 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20   safe to pass a 
18fb0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72  result table dir
18fc0 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65  ectly to [sqlite
18fd0 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20  3_free()]..** A 
18fe0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f  result table sho
18ff0 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  uld be deallocat
19000 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
19010 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e  3_free_table()].
19020 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65  .**.** ^(As an e
19030 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65  xample of the re
19040 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61  sult table forma
19050 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65  t, suppose a que
19060 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  ry result.** is 
19070 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
19080 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
19090 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61  re>.**        Na
190a0 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a  me        | Age.
190b0 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d  **        ------
190c0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
190d0 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63  -.**        Alic
190e0 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20  e       | 43.** 
190f0 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20         Bob      
19100 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20     | 28.**      
19110 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20    Cindy       | 
19120 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  21.** </pre></bl
19130 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
19140 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f  There are two co
19150 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20  lumn (M==2) and 
19160 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33  three rows (N==3
19170 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20  ).  Thus the.** 
19180 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73  result table has
19190 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70   8 entries.  Sup
191a0 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20  pose the result 
191b0 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a  table is stored.
191c0 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e  ** in an array n
191d0 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20  ames azResult.  
191e0 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f  Then azResult ho
191f0 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74  lds this content
19200 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
19210 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
19220 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
19230 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a  ;0] = "Name";.**
19240 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
19250 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b  &#91;1] = "Age";
19260 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
19270 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c  ult&#91;2] = "Al
19280 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ice";.**        
19290 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20  azResult&#91;3] 
192a0 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20  = "43";.**      
192b0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34    azResult&#91;4
192c0 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20  ] = "Bob";.**   
192d0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
192e0 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20  1;5] = "28";.** 
192f0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
19300 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22  #91;6] = "Cindy"
19310 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
19320 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32  sult&#91;7] = "2
19330 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  1";.** </pre></b
19340 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
19350 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
19360 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63  get_table() func
19370 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f  tion evaluates o
19380 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65  ne or more.** se
19390 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
193a0 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  d SQL statements
193b0 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   in the zero-ter
193c0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a  minated UTF-8.**
193d0 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32   string of its 2
193e0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
193f0 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c   returns a resul
19400 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a  t table to the.*
19410 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20  * pointer given 
19420 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d  in its 3rd param
19430 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65  eter..**.** Afte
19440 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
19450 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  n has finished w
19460 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66  ith the result f
19470 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  rom sqlite3_get_
19480 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d  table(),.** it m
19490 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65 73  ust pass the res
194a0 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65  ult table pointe
194b0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  r to sqlite3_fre
194c0 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64  e_table() in ord
194d0 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65  er to.** release
194e0 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74   the memory that
194f0 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20   was malloced.  
19500 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77  Because of the w
19510 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ay the.** [sqlit
19520 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70  e3_malloc()] hap
19530 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69  pens within sqli
19540 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
19550 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20   the calling.** 
19560 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  function must no
19570 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73  t try to call [s
19580 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64  qlite3_free()] d
19590 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a  irectly.  Only.*
195a0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  * [sqlite3_free_
195b0 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65  table()] is able
195c0 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20   to release the 
195d0 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20  memory properly 
195e0 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a  and safely..**.*
195f0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
19600 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66  t_table() interf
19610 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74  ace is implement
19620 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20  ed as a wrapper 
19630 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  around.** [sqlit
19640 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65  e3_exec()].  The
19650 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
19660 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  le() routine doe
19670 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73  s not have acces
19680 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65  s.** to any inte
19690 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74  rnal data struct
196a0 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ures of SQLite. 
196b0 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68   It uses only th
196c0 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65  e public.** inte
196d0 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65  rface defined he
196e0 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71  re.  As a conseq
196f0 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68  uence, errors th
19700 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a  at occur in the.
19710 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72  ** wrapper layer
19720 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
19730 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65  internal [sqlite
19740 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61  3_exec()] call a
19750 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63  re not.** reflec
19760 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e  ted in subsequen
19770 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
19780 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f  te3_errcode()] o
19790 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  r.** [sqlite3_er
197a0 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  rmsg()]..*/.int 
197b0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
197c0 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
197d0 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e  ,          /* An
197e0 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
197f0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
19800 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c  zSql,     /* SQL
19810 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
19820 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61   */.  char ***pa
19830 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52  zResult,    /* R
19840 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75  esults of the qu
19850 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ery */.  int *pn
19860 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f  Row,           /
19870 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
19880 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20  lt rows written 
19890 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  here */.  int *p
198a0 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20  nColumn,        
198b0 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
198c0 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74  ult columns writ
198d0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68  ten here */.  ch
198e0 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20  ar **pzErrmsg   
198f0 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
19900 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
19910 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .);.void sqlite3
19920 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72  _free_table(char
19930 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a   **result);../*.
19940 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72  ** CAPI3REF: For
19950 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72  matted String Pr
19960 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  inting Functions
19970 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
19980 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61  tines are work-a
19990 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72  likes of the "pr
199a0 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f  intf()" family o
199b0 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66  f functions.** f
199c0 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
199d0 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a   C library..**.*
199e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
199f0 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c  printf() and sql
19a00 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20  ite3_vmprintf() 
19a10 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74  routines write t
19a20 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20  heir.** results 
19a30 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
19a40 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
19a50 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a  e3_malloc()]..**
19a60 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   The strings ret
19a70 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74  urned by these t
19a80 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75  wo routines shou
19a90 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65  ld be.** release
19aa0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72  d by [sqlite3_fr
19ab0 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f  ee()].  ^Both ro
19ac0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a  utines return a.
19ad0 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
19ae0 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  if [sqlite3_mall
19af0 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20  oc()] is unable 
19b00 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75  to allocate enou
19b10 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20  gh.** memory to 
19b20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69  hold the resulti
19b30 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ng string..**.**
19b40 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73   ^(The sqlite3_s
19b50 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
19b60 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
19b70 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f  "snprintf()" fro
19b80 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72  m.** the standar
19b90 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68  d C library.  Th
19ba0 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74  e result is writ
19bb0 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ten into the.** 
19bc0 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20  buffer supplied 
19bd0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
19be0 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69  rameter whose si
19bf0 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a  ze is given by.*
19c00 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  * the first para
19c10 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74  meter. Note that
19c20 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68   the order of th
19c30 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70  e.** first two p
19c40 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76  arameters is rev
19c50 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69  ersed from snpri
19c60 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69  ntf().)^  This i
19c70 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63  s an.** historic
19c80 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74  al accident that
19c90 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64   cannot be fixed
19ca0 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
19cb0 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  g.** backwards c
19cc0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e  ompatibility.  ^
19cd0 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20  (Note also that 
19ce0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
19cf0 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
19d00 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62  pointer to its b
19d10 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66  uffer instead of
19d20 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
19d30 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74  * characters act
19d40 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e  ually written in
19d50 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e  to the buffer.)^
19d60 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a    We admit that.
19d70 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
19d80 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74   characters writ
19d90 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d  ten would be a m
19da0 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72  ore useful retur
19db0 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77  n.** value but w
19dc0 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20  e cannot change 
19dd0 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
19de0 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
19df0 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20  printf().** now 
19e00 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
19e10 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
19e20 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61  **.** ^As long a
19e30 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a  s the buffer siz
19e40 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  e is greater tha
19e50 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f  n zero, sqlite3_
19e60 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75  snprintf().** gu
19e70 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
19e80 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61  e buffer is alwa
19e90 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
19ea0 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a  ed.  ^The first.
19eb0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22  ** parameter "n"
19ec0 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69   is the total si
19ed0 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
19ee0 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63  , including spac
19ef0 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72  e for.** the zer
19f00 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53  o terminator.  S
19f10 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74  o the longest st
19f20 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65  ring that can be
19f30 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77   completely.** w
19f40 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e  ritten will be n
19f50 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -1 characters..*
19f60 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
19f70 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  3_vsnprintf() ro
19f80 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 72  utine is a varar
19f90 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71  gs version of sq
19fa0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
19fb0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
19fc0 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65  utines all imple
19fd0 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69  ment some additi
19fe0 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a  onal formatting.
19ff0 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20  ** options that 
1a000 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63  are useful for c
1a010 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20  onstructing SQL 
1a020 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41  statements..** A
1a030 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20  ll of the usual 
1a040 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74  printf() formatt
1a050 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c  ing options appl
1a060 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c  y.  In addition,
1a070 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65   there.** is are
1a080 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64   "%q", "%Q", and
1a090 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a   "%z" options..*
1a0a0 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70  *.** ^(The %q op
1a0b0 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1a0c0 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75  %s in that it su
1a0d0 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d  bstitutes a nul-
1a0e0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
1a0f0 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72  ring from the ar
1a100 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75  gument list.  Bu
1a110 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65  t %q also double
1a120 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61  s every '\'' cha
1a130 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73  racter..** %q is
1a140 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73   designed for us
1a150 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e  e inside a strin
1a160 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79  g literal.)^  By
1a170 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27   doubling each '
1a180 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  \''.** character
1a190 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74   it escapes that
1a1a0 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61   character and a
1a1b0 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69  llows it to be i
1a1c0 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20  nserted into.** 
1a1d0 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  the string..**.*
1a1e0 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61  * For example, a
1a1f0 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67  ssume the string
1a200 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20   variable zText 
1a210 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73  contains text as
1a220 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1a230 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1a240 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78  >.**  char *zTex
1a250 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70  t = "It's a happ
1a260 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72  y day!";.** </pr
1a270 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1a280 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73  **.** One can us
1a290 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61  e this text in a
1a2a0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
1a2b0 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1a2c0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1a2d0 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
1a2e0 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
1a2f0 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
1a300 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27  O table VALUES('
1a310 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  %q')", zText);.*
1a320 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
1a330 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
1a340 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
1a350 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
1a360 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1a370 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  e>.**.** Because
1a380 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73   the %q format s
1a390 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74  tring is used, t
1a3a0 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  he '\'' characte
1a3b0 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73  r in zText.** is
1a3c0 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65   escaped and the
1a3d0 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69   SQL generated i
1a3e0 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
1a3f0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1a400 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
1a410 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
1a420 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70  UES('It''s a hap
1a430 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70  py day!').** </p
1a440 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1a450 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63  .**.** This is c
1a460 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20  orrect.  Had we 
1a470 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20  used %s instead 
1a480 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72  of %q, the gener
1a490 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c  ated SQL.** woul
1a4a0 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69  d have looked li
1a4b0 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
1a4c0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1a4d0 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
1a4e0 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
1a4f0 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
1a500 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  !');.** </pre></
1a510 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1a520 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78  * This second ex
1a530 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20  ample is an SQL 
1a540 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41  syntax error.  A
1a550 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65  s a general rule
1a560 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61   you should.** a
1a570 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73  lways use %q ins
1a580 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20  tead of %s when 
1a590 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69  inserting text i
1a5a0 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74  nto a string lit
1a5b0 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  eral..**.** ^(Th
1a5c0 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %Q option work
1a5d0 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74  s like %q except
1a5e0 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69   it also adds si
1a5f0 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75  ngle quotes arou
1a600 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64  nd.** the outsid
1a610 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73  e of the total s
1a620 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e  tring.  Addition
1a630 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72  ally, if the par
1a640 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a  ameter in the.**
1a650 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69   argument list i
1a660 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1a670 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73  , %Q substitutes
1a680 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22   the text "NULL"
1a690 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e   (without.** sin
1a6a0 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20  gle quotes).)^  
1a6b0 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  So, for example,
1a6c0 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a   one could say:.
1a6d0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1a6e0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
1a6f0 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
1a700 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
1a710 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
1a720 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b  ES(%Q)", zText);
1a730 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
1a740 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
1a750 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
1a760 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
1a770 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1a780 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ote>.**.** The c
1a790 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72  ode above will r
1a7a0 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20  ender a correct 
1a7b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
1a7c0 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72   the zSQL.** var
1a7d0 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68  iable even if th
1a7e0 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65  e zText variable
1a7f0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1a800 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  er..**.** ^(The 
1a810 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%z" formatting 
1a820 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
1a830 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20  e "%s" but with 
1a840 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20  the.** addition 
1a850 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73  that after the s
1a860 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72  tring has been r
1a870 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69  ead and copied i
1a880 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  nto.** the resul
1a890 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  t, [sqlite3_free
1a8a0 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e  ()] is called on
1a8b0 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
1a8c0 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71  g.)^.*/.char *sq
1a8d0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f  lite3_mprintf(co
1a8e0 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a  nst char*,...);.
1a8f0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d  char *sqlite3_vm
1a900 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
1a910 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68  r*, va_list);.ch
1a920 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72  ar *sqlite3_snpr
1a930 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
1a940 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29  onst char*, ...)
1a950 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
1a960 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  vsnprintf(int,ch
1a970 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1a980 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a   va_list);../*.*
1a990 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
1a9a0 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75  ry Allocation Su
1a9b0 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68  bsystem.**.** Th
1a9c0 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73  e SQLite core us
1a9d0 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72  es these three r
1a9e0 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20  outines for all 
1a9f0 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e  of its own.** in
1aa00 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c  ternal memory al
1aa10 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20  location needs. 
1aa20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72  "Core" in the pr
1aa30 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a  evious sentence.
1aa40 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ** does not incl
1aa50 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  ude operating-sy
1aa60 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46  stem specific VF
1aa70 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
1aa80 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77  .  The.** Window
1aa90 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76  s VFS uses nativ
1aaa0 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  e malloc() and f
1aab0 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f  ree() for some o
1aac0 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
1aad0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61   ^The sqlite3_ma
1aae0 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72  lloc() routine r
1aaf0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1ab00 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f   to a block.** o
1ab10 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73  f memory at leas
1ab20 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e  t N bytes in len
1ab30 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20  gth, where N is 
1ab40 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
1ab50 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  * ^If sqlite3_ma
1ab60 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65  lloc() is unable
1ab70 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69   to obtain suffi
1ab80 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65  cient free.** me
1ab90 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73  mory, it returns
1aba0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1abb0 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65    ^If the parame
1abc0 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69  ter N to.** sqli
1abd0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
1abe0 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65  zero or negative
1abf0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61   then sqlite3_ma
1ac00 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a  lloc() returns.*
1ac10 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
1ac20 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
1ac30 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1ac40 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70  with a pointer p
1ac50 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
1ac60 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
1ac70 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
1ac80 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
1ac90 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d  eleases that mem
1aca0 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69  ory so.** that i
1acb0 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65  t might be reuse
1acc0 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
1acd0 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20  _free() routine 
1ace0 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66  is.** a no-op if
1acf0 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
1ad00 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
1ad10 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20   Passing a NULL 
1ad20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71  pointer.** to sq
1ad30 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
1ad40 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72  harmless.  After
1ad50 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65   being freed, me
1ad60 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  mory.** should n
1ad70 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e  either be read n
1ad80 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65  or written.  Eve
1ad90 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f  n reading previo
1ada0 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65  usly freed.** me
1adb0 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c  mory might resul
1adc0 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74  t in a segmentat
1add0 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68  ion fault or oth
1ade0 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e  er severe error.
1adf0 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75  .** Memory corru
1ae00 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74  ption, a segment
1ae10 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20  ation fault, or 
1ae20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
1ae30 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75  or.** might resu
1ae40 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72  lt if sqlite3_fr
1ae50 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77  ee() is called w
1ae60 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  ith a non-NULL p
1ae70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77  ointer that.** w
1ae80 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20  as not obtained 
1ae90 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
1aea0 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
1aeb0 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a  _realloc()..**.*
1aec0 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
1aed0 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66  realloc() interf
1aee0 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
1aef0 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f  resize a.** prio
1af00 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  r memory allocat
1af10 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61  ion to be at lea
1af20 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72  st N bytes, wher
1af30 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65  e N is the.** se
1af40 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
1af50 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   The memory allo
1af60 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73  cation to be res
1af70 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73  ized is the firs
1af80 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29  t.** parameter.)
1af90 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72 73 74  ^ ^ If the first
1afa0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1afb0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a  lite3_realloc().
1afc0 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
1afd0 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65  nter then its be
1afe0 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69  havior is identi
1aff0 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  cal to calling.*
1b000 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1b010 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 74  (N) where N is t
1b020 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1b030 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1b040 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66  ealloc()..** ^If
1b050 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1b060 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1b070 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  _realloc() is ze
1b080 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76  ro or.** negativ
1b090 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  e then the behav
1b0a0 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74  ior is exactly t
1b0b0 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69  he same as calli
1b0c0 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72  ng.** sqlite3_fr
1b0d0 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69 73  ee(P) where P is
1b0e0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
1b0f0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1b100 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73  realloc()..** ^s
1b110 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1b120 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1b130 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61  er to a memory a
1b140 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
1b150 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1b160 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c   in size or NULL
1b170 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d   if sufficient m
1b180 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c  emory is unavail
1b190 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69  able..** ^If M i
1b1a0 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
1b1b0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1b1c0 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d  on, then min(N,M
1b1d0 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68  ) bytes.** of th
1b1e0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1b1f0 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e  on are copied in
1b200 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
1b210 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72   of buffer retur
1b220 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
1b230 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  3_realloc() and 
1b240 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1b250 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a  tion is freed..*
1b260 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65  * ^If sqlite3_re
1b270 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20  alloc() returns 
1b280 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70  NULL, then the p
1b290 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  rior allocation.
1b2a0 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e  ** is not freed.
1b2b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f  .**.** ^The memo
1b2c0 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ry returned by s
1b2d0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1b2e0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  and sqlite3_real
1b2f0 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61  loc().** is alwa
1b300 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74  ys aligned to at
1b310 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65   least an 8 byte
1b320 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f   boundary, or to
1b330 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75   a.** 4 byte bou
1b340 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51  ndary if the [SQ
1b350 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47  LITE_4_BYTE_ALIG
1b360 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70  NED_MALLOC] comp
1b370 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
1b380 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
1b390 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73  * In SQLite vers
1b3a0 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e  ion 3.5.0 and 3.
1b3b0 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73  5.1, it was poss
1b3c0 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a  ible to define.*
1b3d0 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49  * the SQLITE_OMI
1b3e0 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54  T_MEMORY_ALLOCAT
1b3f0 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20  ION which would 
1b400 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d  cause the built-
1b410 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  in.** implementa
1b420 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f  tion of these ro
1b430 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69  utines to be omi
1b440 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61  tted.  That capa
1b450 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20  bility.** is no 
1b460 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e  longer provided.
1b470 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20    Only built-in 
1b480 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
1b490 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a  s can be used..*
1b4a0 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51  *.** Prior to SQ
1b4b0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
1b4c0 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73  .10, the Windows
1b4d0 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
1b4e0 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68  yer called.** th
1b4f0 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
1b500 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72  ) and free() dir
1b510 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65  ectly when conve
1b520 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d  rting.** filenam
1b530 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55  es between the U
1b540 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73  TF-8 encoding us
1b550 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
1b560 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c  and whatever fil
1b570 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69  ename encoding i
1b580 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61  s used by the pa
1b590 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73  rticular Windows
1b5a0 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e  .** installation
1b5b0 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  .  Memory alloca
1b5c0 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65  tion errors were
1b5d0 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a   detected, but.*
1b5e0 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f  * they were repo
1b5f0 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
1b600 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
1b610 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
1b620 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
1b630 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
1b640 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
1b650 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b  r arguments to [
1b660 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1b670 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
1b680 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20  lloc()].** must 
1b690 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f  be either NULL o
1b6a0 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20  r else pointers 
1b6b0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
1b6c0 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74  prior.** invocat
1b6d0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
1b6e0 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
1b6f0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1b700 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f   that have.** no
1b710 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61  t yet been relea
1b720 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  sed..**.** The a
1b730 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
1b740 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74  not read or writ
1b750 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a  e any part of.**
1b760 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f   a block of memo
1b770 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20  ry after it has 
1b780 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73  been released us
1b790 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1b7a0 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  free()] or [sqli
1b7b0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a  te3_realloc()]..
1b7c0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
1b7d0 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f  _malloc(int);.vo
1b7e0 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
1b7f0 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  loc(void*, int);
1b800 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
1b810 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ee(void*);../*.*
1b820 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
1b830 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61  ry Allocator Sta
1b840 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51  tistics.**.** SQ
1b850 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68  Lite provides th
1b860 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63  ese two interfac
1b870 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67  es for reporting
1b880 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a   on the status.*
1b890 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
1b8a0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71  3_malloc()], [sq
1b8b0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61  lite3_free()], a
1b8c0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
1b8d0 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e  loc()].** routin
1b8e0 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74  es, which form t
1b8f0 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  he built-in memo
1b900 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
1b910 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  bsystem..**.** ^
1b920 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
1b930 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74  ory_used()] rout
1b940 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
1b950 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a  number of bytes.
1b960 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72  ** of memory cur
1b970 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69  rently outstandi
1b980 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74  ng (malloced but
1b990 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20   not freed)..** 
1b9a0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
1b9b0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1b9c0 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
1b9d0 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
1b9e0 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74   value of [sqlit
1b9f0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1ba00 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68  ] since the high
1ba10 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77  -water mark.** w
1ba20 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20  as last reset.  
1ba30 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
1ba40 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
1ba50 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1ba60 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
1ba70 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1ba80 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20  ()] include any 
1ba90 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65  overhead.** adde
1baa0 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69  d by SQLite in i
1bab0 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ts implementatio
1bac0 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
1bad0 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20  lloc()],.** but 
1bae0 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64  not overhead add
1baf0 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e  ed by the any un
1bb00 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20  derlying system 
1bb10 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69  library.** routi
1bb20 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65  nes that [sqlite
1bb30 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20  3_malloc()] may 
1bb40 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  call..**.** ^The
1bb50 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74   memory high-wat
1bb60 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74  er mark is reset
1bb70 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   to the current 
1bb80 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c  value of.** [sql
1bb90 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1bba0 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ()] if and only 
1bbb0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
1bbc0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
1bbd0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1bbe0 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54  ()] is true.  ^T
1bbf0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1bc00 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
1bc10 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1bc20 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67  r(1)] is the hig
1bc30 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
1bc40 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73  prior to the res
1bc50 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  et..*/.sqlite3_i
1bc60 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
1bc70 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a  ory_used(void);.
1bc80 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
1bc90 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1bca0 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74  hwater(int reset
1bcb0 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Flag);../*.** CA
1bcc0 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52  PI3REF: Pseudo-R
1bcd0 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e  andom Number Gen
1bce0 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c  erator.**.** SQL
1bcf0 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68  ite contains a h
1bd00 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75  igh-quality pseu
1bd10 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72  do-random number
1bd20 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47   generator (PRNG
1bd30 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c  ) used to.** sel
1bd40 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49  ect random [ROWI
1bd50 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e  D | ROWIDs] when
1bd60 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72   inserting new r
1bd70 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61  ecords into a ta
1bd80 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65  ble that.** alre
1bd90 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72  ady uses the lar
1bda0 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52  gest possible [R
1bdb0 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47  OWID].  The PRNG
1bdc0 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f   is also used fo
1bdd0 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69  r.** the build-i
1bde0 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72  n random() and r
1bdf0 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20  andomblob() SQL 
1be00 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73  functions.  This
1be10 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
1be20 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  s.** application
1be30 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
1be40 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74  same PRNG for ot
1be50 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a  her purposes..**
1be60 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74  .** ^A call to t
1be70 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
1be80 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61  es N bytes of ra
1be90 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75  ndomness into bu
1bea0 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ffer P..**.** ^T
1beb0 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
1bec0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e  is routine is in
1bed0 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e  voked (either in
1bee0 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a  ternally or by.*
1bef0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
1bf00 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73  n) the PRNG is s
1bf10 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64  eeded using rand
1bf20 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a  omness obtained.
1bf30 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e  ** from the xRan
1bf40 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f  domness method o
1bf50 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
1bf60 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
1bf70 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73  ct..** ^On all s
1bf80 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
1bf90 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64  tions, the pseud
1bfa0 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20  o-randomness is 
1bfb0 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74  generated.** int
1bfc0 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68  ernally and with
1bfd0 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20  out recourse to 
1bfe0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
1bff0 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a  ] xRandomness.**
1c000 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64   method..*/.void
1c010 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e   sqlite3_randomn
1c020 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20  ess(int N, void 
1c030 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *P);../*.** CAPI
1c040 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69  3REF: Compile-Ti
1c050 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  me Authorization
1c060 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
1c070 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
1c080 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68  egisters an auth
1c090 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1c0a0 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
1c0b0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
1c0c0 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70  onnection], supp
1c0d0 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
1c0e0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  t argument..** ^
1c0f0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
1c100 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1c110 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
1c120 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
1c130 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
1c140 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1c150 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
1c160 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
1c170 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
1c180 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1c190 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1c1a0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
1c1b0 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a    ^At various.**
1c1c0 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74   points during t
1c1d0 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70  he compilation p
1c1e0 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63  rocess, as logic
1c1f0 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65   is being create
1c200 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20  d.** to perform 
1c210 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c  various actions,
1c220 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1c230 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1c240 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66  ked to.** see if
1c250 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61   those actions a
1c260 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68  re allowed.  ^Th
1c270 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1c280 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20  lback should.** 
1c290 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
1c2a0 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20  K] to allow the 
1c2b0 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f  action, [SQLITE_
1c2c0 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c  IGNORE] to disal
1c2d0 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69  low the.** speci
1c2e0 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61  fic action but a
1c2f0 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61  llow the SQL sta
1c300 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e  tement to contin
1c310 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ue to be.** comp
1c320 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  iled, or [SQLITE
1c330 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20  _DENY] to cause 
1c340 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73  the entire SQL s
1c350 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a  tatement to be.*
1c360 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20  * rejected with 
1c370 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74  an error.  ^If t
1c380 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1c390 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
1c3a0 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65  * any value othe
1c3b0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49  r than [SQLITE_I
1c3c0 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  GNORE], [SQLITE_
1c3d0 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OK], or [SQLITE_
1c3e0 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  DENY].** then th
1c3f0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
1c400 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
1c410 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
1c420 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68   triggered.** th
1c430 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  e authorizer wil
1c440 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
1c450 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
1c460 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c  .** When the cal
1c470 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
1c480 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20  QLITE_OK], that 
1c490 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74  means the operat
1c4a0 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  ion.** requested
1c4b0 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74   is ok.  ^When t
1c4c0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1c4d0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59  rns [SQLITE_DENY
1c4e0 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ], the.** [sqlit
1c4f0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1c500 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
1c510 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
1c520 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  ed the.** author
1c530 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
1c540 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
1c550 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20  sage explaining 
1c560 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69  that.** access i
1c570 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a  s denied. .**.**
1c580 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
1c590 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
1c5a0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1c5b0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
1c5c0 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
1c5d0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
1c5e0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1c5f0 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20  er() interface. 
1c600 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
1c610 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
1c620 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
1c630 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43  nteger [SQLITE_C
1c640 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
1c650 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
1c660 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75  s.** the particu
1c670 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  lar action to be
1c680 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68   authorized. ^Th
1c690 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
1c6a0 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
1c6b0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
1c6c0 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  ack are zero-ter
1c6d0 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
1c6e0 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64  that contain add
1c6f0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69  itional.** detai
1c700 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
1c710 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
1c720 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ized..**.** ^If 
1c730 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
1c740 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  is [SQLITE_READ]
1c750 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  .** and the call
1c760 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1c770 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
1c780 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
1c790 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74  ed statement] st
1c7a0 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
1c7b0 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69  ructed to substi
1c7c0 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76  tute.** a NULL v
1c7d0 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
1c7e0 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
1c7f0 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
1c800 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69  e.** been read i
1c810 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61  f [SQLITE_OK] ha
1c820 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e  d been returned.
1c830 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47    The [SQLITE_IG
1c840 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20  NORE].** return 
1c850 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64  can be used to d
1c860 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64  eny an untrusted
1c870 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20   user access to 
1c880 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f  individual.** co
1c890 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65  lumns of a table
1c8a0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  ..** ^If the act
1c8b0 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
1c8c0 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20  ITE_DELETE] and 
1c8d0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1c8e0 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
1c8f0 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
1c900 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74   [DELETE] operat
1c910 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74  ion proceeds but
1c920 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74   the.** [truncat
1c930 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20  e optimization] 
1c940 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20  is disabled and 
1c950 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c  all rows are del
1c960 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  eted individuall
1c970 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  y..**.** An auth
1c980 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
1c990 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
1c9a0 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67  pare | preparing
1c9b0 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  ].** SQL stateme
1c9c0 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72  nts from an untr
1c9d0 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f  usted source, to
1c9e0 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
1c9f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
1ca00 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ** do not try to
1ca10 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65   access data the
1ca20 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  y are not allowe
1ca30 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61  d to see, or tha
1ca40 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
1ca50 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20   try to execute 
1ca60 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d  malicious statem
1ca70 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65  ents that damage
1ca80 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20   the database.  
1ca90 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
1caa0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
1cab0 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20  ay allow a user 
1cac0 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61  to enter arbitra
1cad0 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65  ry.** SQL querie
1cae0 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e  s for evaluation
1caf0 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20   by a database. 
1cb00 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61   But the applica
1cb10 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  tion does.** not
1cb20 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74   want the user t
1cb30 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b  o be able to mak
1cb40 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e  e arbitrary chan
1cb50 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ges to the.** da
1cb60 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68  tabase.  An auth
1cb70 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65  orizer could the
1cb80 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63  n be put in plac
1cb90 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75  e while the.** u
1cba0 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20  ser-entered SQL 
1cbb0 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65  is being [sqlite
1cbc0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
1cbd0 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69  ared] that.** di
1cbe0 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
1cbf0 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43  ng except [SELEC
1cc00 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
1cc10 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
1cc20 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70  s that need to p
1cc30 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20  rocess SQL from 
1cc40 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
1cc50 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20  s.** might also 
1cc60 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e  consider lowerin
1cc70 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74  g resource limit
1cc80 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  s using [sqlite3
1cc90 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64  _limit()].** and
1cca0 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61   limiting databa
1ccb0 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68  se size using th
1ccc0 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  e [max_page_coun
1ccd0 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69  t] [PRAGMA].** i
1cce0 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73  n addition to us
1ccf0 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ing an authorize
1cd00 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  r..**.** ^(Only 
1cd10 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69  a single authori
1cd20 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c  zer can be in pl
1cd30 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73  ace on a databas
1cd40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1cd50 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68  at a time.  Each
1cd60 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
1cd70 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1cd80 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
1cd90 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29   previous call.)
1cda0 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20  ^  ^Disable the 
1cdb0 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e  authorizer by in
1cdc0 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20  stalling a NULL 
1cdd0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  callback..** The
1cde0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64   authorizer is d
1cdf0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
1ce00 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  lt..**.** The au
1ce10 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1ce20 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
1ce30 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
1ce40 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
1ce50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1ce60 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1ce70 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1ce80 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65  allback..** Note
1ce90 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
1cea0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
1ceb0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1cec0 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
1ced0 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
1cee0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
1cef0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
1cf00 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
1cf10 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
1cf20 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f   ^When [sqlite3_
1cf30 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73  prepare_v2()] is
1cf40 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65   used to prepare
1cf50 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68   a statement, th
1cf60 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d  e.** statement m
1cf70 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61  ight be re-prepa
1cf80 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69  red during [sqli
1cf90 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20  te3_step()] due 
1cfa0 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20  to a .** schema 
1cfb0 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20  change.  Hence, 
1cfc0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1cfd0 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68  should ensure th
1cfe0 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63  at the.** correc
1cff0 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  t authorizer cal
1d000 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e  lback remains in
1d010 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68   place during th
1d020 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
1d030 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  )]..**.** ^Note 
1d040 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
1d050 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1d060 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72  invoked only dur
1d070 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1d080 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
1d090 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
1d0a0 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
1d0b0 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
1d0c0 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
1d0d0 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
1d0e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
1d0f0 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61  unless.** as sta
1d100 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69  ted in the previ
1d110 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73  ous paragraph, s
1d120 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
1d130 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33  vokes.** sqlite3
1d140 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f  _prepare_v2() to
1d150 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61   reprepare a sta
1d160 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73  tement after a s
1d170 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f  chema change..*/
1d180 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74  .int sqlite3_set
1d190 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73  _authorizer(.  s
1d1a0 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28  qlite3*,.  int (
1d1b0 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e  *xAuth)(void*,in
1d1c0 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  t,const char*,co
1d1d0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1d1e0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1d1f0 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65  *),.  void *pUse
1d200 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  rData.);../*.** 
1d210 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
1d220 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65  izer Return Code
1d230 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
1d240 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1d250 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
1d260 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1d270 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75  on] must.** retu
1d280 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  rn either [SQLIT
1d290 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  E_OK] or one of 
1d2a0 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61  these two consta
1d2b0 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20  nts in order.** 
1d2c0 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65  to signal SQLite
1d2d0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1d2e0 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65  the action is pe
1d2f0 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68  rmitted.  See th
1d300 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65  e.** [sqlite3_se
1d310 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
1d320 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65  uthorizer docume
1d330 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64  ntation] for add
1d340 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
1d350 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  mation..**.** No
1d360 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49  te that SQLITE_I
1d370 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73  GNORE is also us
1d380 65 64 20 61 73 20 61 20 5b 53 51 4c 49 54 45 5f  ed as a [SQLITE_
1d390 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75 72  ROLLBACK | retur
1d3a0 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20  n code].** from 
1d3b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61  the [sqlite3_vta
1d3c0 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d  b_on_conflict()]
1d3d0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23   interface..*/.#
1d3e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
1d3f0 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72  NY   1   /* Abor
1d400 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
1d410 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ent with an erro
1d420 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
1d430 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f  ITE_IGNORE 2   /
1d440 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63  * Don't allow ac
1d450 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20  cess, but don't 
1d460 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f  generate an erro
1d470 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  r */../*.** CAPI
1d480 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
1d490 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a   Action Codes.**
1d4a0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
1d4b0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1d4c0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
1d4d0 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
1d4e0 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68  k function.** th
1d4f0 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  at is invoked to
1d500 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61   authorize certa
1d510 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  in SQL statement
1d520 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a   actions.  The.*
1d530 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
1d540 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
1d550 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
1d560 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69   code that speci
1d570 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74  fies.** what act
1d580 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74  ion is being aut
1d590 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20  horized.  These 
1d5a0 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20  are the integer 
1d5b0 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61  action codes tha
1d5c0 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  t.** the authori
1d5d0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79  zer callback may
1d5e0 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a   be passed..**.*
1d5f0 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63  * These action c
1d600 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69  ode values signi
1d610 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  fy what kind of 
1d620 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20  operation is to 
1d630 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64  be.** authorized
1d640 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34  .  The 3rd and 4
1d650 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
1d660 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69   the authorizati
1d670 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  on.** callback f
1d680 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20  unction will be 
1d690 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55  parameters or NU
1d6a0 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  LL depending on 
1d6b0 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a  which of these.*
1d6c0 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20  * codes is used 
1d6d0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
1d6e0 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20  rameter.  ^(The 
1d6f0 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
1d700 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
1d710 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
1d720 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
1d730 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c  atabase ("main",
1d740 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e   "temp",.** etc.
1d750 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e  ) if applicable.
1d760 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72  )^  ^The 6th par
1d770 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
1d780 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1d790 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  k.** is the name
1d7a0 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
1d7b0 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
1d7c0 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
1d7d0 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68  nsible for.** th
1d7e0 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
1d7f0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
1d800 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
1d810 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
1d820 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51  .** top-level SQ
1d830 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a  L code..*/./****
1d840 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1d850 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1d860 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a  ******* 3rd ****
1d870 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a  ******** 4th ***
1d880 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e  ********/.#defin
1d890 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1d8a0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31  INDEX          1
1d8b0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1d8c0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
1d8d0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1d8e0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1d8f0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20  ABLE          2 
1d900 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1d910 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1d920 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1d930 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1d940 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20  MP_INDEX     3  
1d950 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1d960 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1d970 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1d980 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1d990 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20  P_TABLE     4   
1d9a0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1d9b0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1d9c0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1d9d0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1d9e0 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f  _TRIGGER   5   /
1d9f0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
1da00 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1da10 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1da20 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1da30 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a  VIEW      6   /*
1da40 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
1da50 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1da60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1da70 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45  TE_CREATE_TRIGGE
1da80 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  R        7   /* 
1da90 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1daa0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1dab0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1dac0 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20  E_CREATE_VIEW   
1dad0 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56          8   /* V
1dae0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1daf0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1db00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1db10 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
1db20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61         9   /* Ta
1db30 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1db40 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1db50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1db60 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20  DROP_INDEX      
1db70 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64       10   /* Ind
1db80 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1db90 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1dba0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1dbb0 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ROP_TABLE       
1dbc0 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c      11   /* Tabl
1dbd0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1dbe0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1dbf0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1dc00 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  OP_TEMP_INDEX   
1dc10 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78     12   /* Index
1dc20 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1dc30 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1dc40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1dc50 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  P_TEMP_TABLE    
1dc60 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    13   /* Table 
1dc70 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1dc80 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1dc90 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1dca0 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
1dcb0 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72   14   /* Trigger
1dcc0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1dcd0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1dce0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1dcf0 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20  TEMP_VIEW       
1dd00 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  15   /* View Nam
1dd10 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1dd20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1dd30 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1dd40 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31  RIGGER         1
1dd50 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  6   /* Trigger N
1dd60 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1dd70 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1dd80 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49  e SQLITE_DROP_VI
1dd90 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37  EW            17
1dda0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1ddb0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1ddc0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1ddd0 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20   SQLITE_INSERT  
1dde0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20               18 
1ddf0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1de00 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1de10 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1de20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20  SQLITE_PRAGMA   
1de30 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20              19  
1de40 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20   /* Pragma Name 
1de50 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e      1st arg or N
1de60 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ULL */.#define S
1de70 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20  QLITE_READ      
1de80 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20             20   
1de90 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1dea0 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
1deb0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1dec0 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20  LITE_SELECT     
1ded0 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f            21   /
1dee0 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
1def0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1df00 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1df10 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20  ITE_TRANSACTION 
1df20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a           22   /*
1df30 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
1df40 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1df50 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1df60 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20  TE_UPDATE       
1df70 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
1df80 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1df90 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
1dfa0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1dfb0 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20  E_ATTACH        
1dfc0 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46         24   /* F
1dfd0 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e  ilename        N
1dfe0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1dff0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e000 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20  _DETACH         
1e010 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61        25   /* Da
1e020 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55  tabase Name   NU
1e030 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1e040 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e050 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20  ALTER_TABLE     
1e060 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74       26   /* Dat
1e070 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62  abase Name   Tab
1e080 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1e090 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
1e0a0 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  EINDEX          
1e0b0 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65      27   /* Inde
1e0c0 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  x Name      NULL
1e0d0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1e0e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
1e0f0 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20  ALYZE           
1e100 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65     28   /* Table
1e110 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1e120 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1e130 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1e140 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ATE_VTABLE      
1e150 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20    29   /* Table 
1e160 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
1e170 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1e180 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1e190 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  _VTABLE         
1e1a0 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   30   /* Table N
1e1b0 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
1e1c0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1e1d0 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54  ine SQLITE_FUNCT
1e1e0 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  ION             
1e1f0 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  31   /* NULL    
1e200 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e          Function
1e210 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69   Name   */.#defi
1e220 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f  ne SQLITE_SAVEPO
1e230 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33  INT            3
1e240 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
1e250 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74         Savepoint
1e260 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e   Name  */.#defin
1e270 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20  e SQLITE_COPY   
1e280 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
1e290 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20     /* No longer 
1e2a0 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
1e2b0 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67  API3REF: Tracing
1e2c0 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46   And Profiling F
1e2d0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
1e2e0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
1e2f0 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20  gister callback 
1e300 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63  functions that c
1e310 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a  an be used for.*
1e320 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72  * tracing and pr
1e330 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63  ofiling the exec
1e340 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61  ution of SQL sta
1e350 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
1e360 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
1e370 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
1e380 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63   by sqlite3_trac
1e390 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  e() is invoked a
1e3a0 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d  t.** various tim
1e3b0 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73  es when an SQL s
1e3c0 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e  tatement is bein
1e3d0 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65  g run by [sqlite
1e3e0 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54  3_step()]..** ^T
1e3f0 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
1e400 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  () callback is i
1e410 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54  nvoked with a UT
1e420 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
1e430 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74   the.** SQL stat
1e440 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68  ement text as th
1e450 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  e statement firs
1e460 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69  t begins executi
1e470 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f  ng..** ^(Additio
1e480 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63  nal sqlite3_trac
1e490 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69  e() callbacks mi
1e4a0 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20  ght occur.** as 
1e4b0 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73  each triggered s
1e4c0 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74  ubprogram is ent
1e4d0 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62  ered.  The callb
1e4e0 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72  acks for trigger
1e4f0 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55  s.** contain a U
1e500 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  TF-8 SQL comment
1e510 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73   that identifies
1e520 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a   the trigger.)^.
1e530 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
1e540 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
1e550 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
1e560 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20  e3_profile() is 
1e570 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61  invoked.** as ea
1e580 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
1e590 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65   finishes.  ^The
1e5a0 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
1e5b0 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68  k contains.** th
1e5c0 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
1e5d0 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e  ment text and an
1e5e0 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c   estimate of wal
1e5f0 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20  l-clock time.** 
1e600 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74  of how long that
1e610 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20   statement took 
1e620 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72  to run.  ^The pr
1e630 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  ofile callback.*
1e640 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69  * time is in uni
1e650 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64  ts of nanosecond
1e660 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63  s, however the c
1e670 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  urrent implement
1e680 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79  ation.** is only
1e690 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c   capable of mill
1e6a0 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69  isecond resoluti
1e6b0 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65  on so the six le
1e6c0 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a  ast significant.
1e6d0 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65  ** digits in the
1e6e0 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e   time are meanin
1e6f0 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76  gless.  Future v
1e700 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
1e710 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69  e.** might provi
1e720 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c  de greater resol
1e730 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f  ution on the pro
1e740 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  filer callback. 
1e750 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
1e760 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69  profile() functi
1e770 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  on is considered
1e780 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
1e790 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20  d is.** subject 
1e7a0 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74  to change in fut
1e7b0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
1e7c0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20  SQLite..*/.void 
1e7d0 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73  *sqlite3_trace(s
1e7e0 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78  qlite3*, void(*x
1e7f0 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  Trace)(void*,con
1e800 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a  st char*), void*
1e810 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49  );.SQLITE_EXPERI
1e820 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c  MENTAL void *sql
1e830 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c  ite3_profile(sql
1e840 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a  ite3*,.   void(*
1e850 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c  xProfile)(void*,
1e860 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69  const char*,sqli
1e870 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69  te3_uint64), voi
1e880 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1e890 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67  3REF: Query Prog
1e8a0 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  ress Callbacks.*
1e8b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1e8c0 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
1e8d0 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65  er(D,N,X,P) inte
1e8e0 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65  rface causes the
1e8f0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
1e900 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e  ction X to be in
1e910 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c  voked periodical
1e920 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72  ly during long r
1e930 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a  unning calls to.
1e940 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
1e950 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
1e960 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ep()] and [sqlit
1e970 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
1e980 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  for.** database 
1e990 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41  connection D.  A
1e9a0 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f  n example use fo
1e9b0 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66  r this.** interf
1e9c0 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61  ace is to keep a
1e9d0 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72   GUI updated dur
1e9e0 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72  ing a large quer
1e9f0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61  y..**.** ^The pa
1ea00 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 73  rameter P is pas
1ea10 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
1ea20 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
1ea30 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c  r to the .** cal
1ea40 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58  lback function X
1ea50 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  .  ^The paramete
1ea60 72 20 4e 20 69 73 20 74 68 65 20 6e 75 6d 62 65  r N is the numbe
1ea70 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61  r of .** [virtua
1ea80 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75  l machine instru
1ea90 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65  ctions] that are
1eaa0 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65   evaluated betwe
1eab0 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a  en successive.**
1eac0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
1ead0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 0a  the callback X..
1eae0 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69  **.** ^Only a si
1eaf0 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61  ngle progress ha
1eb00 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66  ndler may be def
1eb10 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65  ined at one time
1eb20 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73   per.** [databas
1eb30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73  e connection]; s
1eb40 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f  etting a new pro
1eb50 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
1eb60 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64  ncels the.** old
1eb70 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20   one.  ^Setting 
1eb80 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e  parameter X to N
1eb90 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65  ULL disables the
1eba0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1ebb0 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72  r..** ^The progr
1ebc0 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61  ess handler is a
1ebd0 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20  lso disabled by 
1ebe0 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76  setting N to a v
1ebf0 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61  alue less.** tha
1ec00 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  n 1..**.** ^If t
1ec10 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
1ec20 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
1ec30 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61  -zero, the opera
1ec40 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72  tion is.** inter
1ec50 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65  rupted.  This fe
1ec60 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65  ature can be use
1ec70 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
1ec80 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74  .** "Cancel" but
1ec90 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f  ton on a GUI pro
1eca0 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78  gress dialog box
1ecb0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67  ..**.** The prog
1ecc0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c  ress handler cal
1ecd0 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
1ece0 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
1ecf0 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
1ed00 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1ed10 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
1ed20 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73  ked the progress
1ed30 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74   handler..** Not
1ed40 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
1ed50 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
1ed60 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
1ed70 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
1ed80 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
1ed90 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
1eda0 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
1edb0 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
1edc0 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
1edd0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70  /.void sqlite3_p
1ede0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
1edf0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69  sqlite3*, int, i
1ee00 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
1ee10 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1ee20 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41  I3REF: Opening A
1ee30 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f   New Database Co
1ee40 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e  nnection.**.** ^
1ee50 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
1ee60 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61  pen an SQLite da
1ee70 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73  tabase file as s
1ee80 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
1ee90 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  .** filename arg
1eea0 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65  ument. ^The file
1eeb0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73  name argument is
1eec0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
1eed0 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c  UTF-8 for.** sql
1eee0 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
1eef0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1ef00 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20  ) and as UTF-16 
1ef10 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
1ef20 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20  te.** order for 
1ef30 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1ef40 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20  . ^(A [database 
1ef50 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
1ef60 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a  le is usually.**
1ef70 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70   returned in *pp
1ef80 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65  Db, even if an e
1ef90 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68  rror occurs.  Th
1efa0 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e  e only exception
1efb0 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53   is that.** if S
1efc0 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
1efd0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
1efe0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b  ry to hold the [
1eff0 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c  sqlite3] object,
1f000 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20  .** a NULL will 
1f010 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  be written into 
1f020 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66  *ppDb instead of
1f030 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
1f040 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f  e [sqlite3].** o
1f050 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68  bject.)^ ^(If th
1f060 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1f070 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65  ened (and/or cre
1f080 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c  ated) successful
1f090 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c  ly, then.** [SQL
1f0a0 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
1f0b0 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
1f0c0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
1f0d0 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e  is returned.)^ ^
1f0e0 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
1f0f0 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71  errmsg()] or [sq
1f100 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
1f110 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62  ] routines can b
1f120 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
1f130 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c  .** an English l
1f140 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74  anguage descript
1f150 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72  ion of the error
1f160 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
1f170 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  lure of any.** o
1f180 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  f the sqlite3_op
1f190 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  en() routines..*
1f1a0 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
1f1b0 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74  t encoding for t
1f1c0 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  he database will
1f1d0 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20   be UTF-8 if.** 
1f1e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
1f1f0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
1f200 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e  2() is called an
1f210 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74  d.** UTF-16 in t
1f220 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
1f230 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f  rder if sqlite3_
1f240 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64  open16() is used
1f250 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20  ..**.** Whether 
1f260 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20  or not an error 
1f270 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69  occurs when it i
1f280 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72  s opened, resour
1f290 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ces.** associate
1f2a0 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  d with the [data
1f2b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1f2c0 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62   handle should b
1f2d0 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a  e released by.**
1f2e0 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
1f2f0 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
1f300 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c   when it is no l
1f310 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a  onger required..
1f320 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1f330 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65  3_open_v2() inte
1f340 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65  rface works like
1f350 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a   sqlite3_open().
1f360 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ** except that i
1f370 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64  t accepts two ad
1f380 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74  ditional paramet
1f390 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ers for addition
1f3a0 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76  al control.** ov
1f3b0 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  er the new datab
1f3c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  ase connection. 
1f3d0 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72   ^(The flags par
1f3e0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c  ameter to.** sql
1f3f0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63  ite3_open_v2() c
1f400 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a  an take one of.*
1f410 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * the following 
1f420 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70  three values, op
1f430 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
1f440 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b  d with the .** [
1f450 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
1f460 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
1f470 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b  EN_FULLMUTEX], [
1f480 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
1f490 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51  EDCACHE],.** [SQ
1f4a0 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
1f4b0 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20  ECACHE], and/or 
1f4c0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
1f4d0 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a  ] flags:)^.**.**
1f4e0 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b   <dl>.** ^(<dt>[
1f4f0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1f500 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ONLY]</dt>.** <d
1f510 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
1f520 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64  s opened in read
1f530 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20  -only mode.  If 
1f540 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65  the database doe
1f550 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79  s not.** already
1f560 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72   exist, an error
1f570 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
1f580 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
1f590 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
1f5a0 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  ADWRITE]</dt>.**
1f5b0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
1f5c0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
1f5d0 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
1f5e0 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c  ing if possible,
1f5f0 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f   or reading.** o
1f600 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20  nly if the file 
1f610 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74  is write protect
1f620 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74  ed by the operat
1f630 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20  ing system.  In 
1f640 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74  either.** case t
1f650 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74  he database must
1f660 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
1f670 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72  otherwise an err
1f680 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
1f690 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
1f6a0 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
1f6b0 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
1f6c0 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
1f6d0 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
1f6e0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1f6f0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
1f700 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e   and writing, an
1f710 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a  d is created if.
1f720 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61  ** it does not a
1f730 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68  lready exist. Th
1f740 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69  is is the behavi
1f750 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79  or that is alway
1f760 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71  s used for.** sq
1f770 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
1f780 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1f790 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  ).</dd>)^.** </d
1f7a0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  l>.**.** If the 
1f7b0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
1f7c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1f7d0 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  () is not one of
1f7e0 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74   the.** combinat
1f7f0 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  ions shown above
1f800 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
1f810 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a  ined with other.
1f820 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
1f830 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54  READONLY | SQLIT
1f840 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a  E_OPEN_* bits].*
1f850 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  * then the behav
1f860 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
1f870 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1f880 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
1f890 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
1f8a0 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  t, then the data
1f8b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1f8c0 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20  ** opens in the 
1f8d0 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  multi-thread [th
1f8e0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73  reading mode] as
1f8f0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e   long as the sin
1f900 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f  gle-thread.** mo
1f910 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  de has not been 
1f920 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
1f930 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
1f940 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b  e.  ^If the.** [
1f950 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
1f960 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
1f970 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  et then the data
1f980 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1f990 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20  opens.** in the 
1f9a0 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
1f9b0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65  ading mode] unle
1f9c0 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  ss single-thread
1f9d0 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73   was.** previous
1f9e0 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63  ly selected at c
1f9f0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
1fa00 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54  tart-time..** ^T
1fa10 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
1fa20 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61  SHAREDCACHE] fla
1fa30 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
1fa40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1fa50 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62   to be.** eligib
1fa60 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65  le to use [share
1fa70 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72  d cache mode], r
1fa80 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
1fa90 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
1faa0 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65  ed.** cache is e
1fab0 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71  nabled using [sq
1fac0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
1fad0 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e  red_cache()].  ^
1fae0 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  The.** [SQLITE_O
1faf0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
1fb00 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
1fb10 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1fb20 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20  ction to not.** 
1fb30 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b  participate in [
1fb40 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
1fb50 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  e] even if it is
1fb60 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
1fb70 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
1fb80 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1fb90 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68  _open_v2() is th
1fba0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a  e name of the.**
1fbb0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
1fbc0 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
1fbd0 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
1fbe0 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
1fbf0 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65  e that.** the ne
1fc00 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
1fc10 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65  ction should use
1fc20 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74  .  ^If the fourt
1fc30 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
1fc40 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
1fc50 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c   then the defaul
1fc60 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
1fc70 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a  object is used..
1fc80 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
1fc90 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f  lename is ":memo
1fca0 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69  ry:", then a pri
1fcb0 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20  vate, temporary 
1fcc0 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
1fcd0 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64  se.** is created
1fce0 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74   for the connect
1fcf0 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d  ion.  ^This in-m
1fd00 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77  emory database w
1fd10 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a  ill vanish when.
1fd20 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
1fd30 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
1fd40 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65  osed.  Future ve
1fd50 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1fd60 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75   might.** make u
1fd70 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c  se of additional
1fd80 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d   special filenam
1fd90 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69  es that begin wi
1fda0 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61  th the ":" chara
1fdb0 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72  cter..** It is r
1fdc0 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
1fdd0 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  when a database 
1fde0 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c  filename actuall
1fdf0 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74  y does begin wit
1fe00 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61  h.** a ":" chara
1fe10 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20  cter you should 
1fe20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e  prefix the filen
1fe30 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e  ame with a pathn
1fe40 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22  ame such as.** "
1fe50 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62  ./" to avoid amb
1fe60 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iguity..**.** ^I
1fe70 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
1fe80 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  s an empty strin
1fe90 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  g, then a privat
1fea0 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20  e, temporary.** 
1feb0 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65  on-disk database
1fec0 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64   will be created
1fed0 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65  .  ^This private
1fee0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
1fef0 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  e.** automatical
1ff00 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f  ly deleted as so
1ff10 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61  on as the databa
1ff20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
1ff30 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b   closed..**.** [
1ff40 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69  [URI filenames i
1ff50 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  n sqlite3_open()
1ff60 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e  ]] <h3>URI Filen
1ff70 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ames</h3>.**.** 
1ff80 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ^If [URI filenam
1ff90 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  e] interpretatio
1ffa0 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e  n is enabled, an
1ffb0 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  d the filename a
1ffc0 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e  rgument.** begin
1ffd0 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20  s with "file:", 
1ffe0 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d  then the filenam
1fff0 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  e is interpreted
20000 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a   as a URI. ^URI.
20010 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65  ** filename inte
20020 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e  rpretation is en
20030 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51  abled if the [SQ
20040 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
20050 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e  lag is.** set in
20060 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
20070 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
20080 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66  open_v2(), or if
20090 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20   it has.** been 
200a0 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79  enabled globally
200b0 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49   using the [SQLI
200c0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f  TE_CONFIG_URI] o
200d0 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a  ption with the.*
200e0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
200f0 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62  g()] method or b
20100 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53  y the [SQLITE_US
20110 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74  E_URI] compile-t
20120 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41  ime option..** A
20130 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73  s of SQLite vers
20140 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66  ion 3.7.7, URI f
20150 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
20160 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  tation is turned
20170 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75   off.** by defau
20180 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72  lt, but future r
20190 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
201a0 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55  e might enable U
201b0 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69  RI filename.** i
201c0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79  nterpretation by
201d0 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22   default.  See "
201e0 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22  [URI filenames]"
201f0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
20200 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
20210 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61  **.** URI filena
20220 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61  mes are parsed a
20230 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20  ccording to RFC 
20240 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52  3986. ^If the UR
20250 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a  I contains an.**
20260 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e   authority, then
20270 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68   it must be eith
20280 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  er an empty stri
20290 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67  ng or the string
202a0 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22   .** "localhost"
202b0 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72  . ^If the author
202c0 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d  ity is not an em
202d0 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c  pty string or "l
202e0 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a  ocalhost", an .*
202f0 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  * error is retur
20300 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65  ned to the calle
20310 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74  r. ^The fragment
20320 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
20330 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73  URI, if .** pres
20340 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e  ent, is ignored.
20350 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
20360 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d  ses the path com
20370 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52  ponent of the UR
20380 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  I as the name of
20390 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a   the disk file.*
203a0 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73  * which contains
203b0 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e   the database. ^
203c0 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69  If the path begi
203d0 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68  ns with a '/' ch
203e0 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65  aracter, .** the
203f0 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65  n it is interpre
20400 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75  ted as an absolu
20410 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65  te path. ^If the
20420 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62   path does not b
20430 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20  egin .** with a 
20440 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61  '/' (meaning tha
20450 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  t the authority 
20460 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74  section is omitt
20470 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29  ed from the URI)
20480 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74  .** then the pat
20490 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
204a0 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70   as a relative p
204b0 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e  ath. .** ^On win
204c0 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20  dows, the first 
204d0 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20  component of an 
204e0 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a  absolute path .*
204f0 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65  * is a drive spe
20500 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e  cification (e.g.
20510 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b   "C:")..**.** [[
20520 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70  core URI query p
20530 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54  arameters]].** T
20540 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  he query compone
20550 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20  nt of a URI may 
20560 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65  contain paramete
20570 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  rs that are inte
20580 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65  rpreted.** eithe
20590 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65  r by SQLite itse
205a0 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53  lf, or by a [VFS
205b0 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d   | custom VFS im
205c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a  plementation]..*
205d0 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72  * SQLite interpr
205e0 65 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  ets the followin
205f0 67 20 74 68 72 65 65 20 71 75 65 72 79 20 70 61  g three query pa
20600 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20  rameters:.**.** 
20610 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  <ul>.**   <li> <
20620 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20  b>vfs</b>: ^The 
20630 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20  "vfs" parameter 
20640 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73  may be used to s
20650 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20  pecify the name 
20660 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20  of.**     a VFS 
20670 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76  object that prov
20680 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ides the operati
20690 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
206a0 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a  ace that should.
206b0 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74  **     be used t
206c0 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  o access the dat
206d0 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69  abase file on di
206e0 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74  sk. ^If this opt
206f0 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a  ion is set to.**
20700 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74       an empty st
20710 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74  ring the default
20720 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75   VFS object is u
20730 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67  sed. ^Specifying
20740 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20   an unknown.**  
20750 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72     VFS is an err
20760 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  or. ^If sqlite3_
20770 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65  open_v2() is use
20780 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70  d and the vfs op
20790 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70  tion is.**     p
207a0 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65  resent, then the
207b0 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62   VFS specified b
207c0 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b  y the option tak
207d0 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76  es precedence ov
207e0 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61  er.**     the va
207f0 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
20800 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
20810 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
20820 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20  en_v2()..**.**  
20830 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62   <li> <b>mode</b
20840 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61  >: ^(The mode pa
20850 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
20860 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f  et to either "ro
20870 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20  ", "rw",.**     
20880 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72  "rwc", or "memor
20890 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74  y". Attempting t
208a0 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20  o set it to any 
208b0 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a  other value is.*
208c0 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e  *     an error)^
208d0 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72  . .**     ^If "r
208e0 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c  o" is specified,
208f0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
20900 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
20910 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20   read-only .**  
20920 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20     access, just 
20930 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  as if the [SQLIT
20940 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
20950 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73   flag had been s
20960 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20  et in the .**   
20970 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74    third argument
20980 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
20990 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d  _v2(). ^If the m
209a0 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ode option is se
209b0 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77  t to .**     "rw
209c0 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  ", then the data
209d0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
209e0 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 62  or read-write (b
209f0 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a  ut not create) .
20a00 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 61  **     access, a
20a10 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e  s if SQLITE_OPEN
20a20 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74 20  _READWRITE (but 
20a30 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  not SQLITE_OPEN_
20a40 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20  CREATE) had .** 
20a50 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56      been set. ^V
20a60 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 71  alue "rwc" is eq
20a70 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
20a80 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20  ing both .**    
20a90 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
20aa0 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54  DWRITE and SQLIT
20ab0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20  E_OPEN_CREATE.  
20ac0 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74  ^If the mode opt
20ad0 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65  ion is.**     se
20ae0 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68  t to "memory" th
20af0 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65  en a pure [in-me
20b00 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20 74  mory database] t
20b10 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a  hat never reads.
20b20 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65 73  **     or writes
20b30 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73   from disk is us
20b40 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72  ed. ^It is an er
20b50 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 61  ror to specify a
20b60 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20   value for.**   
20b70 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d    the mode param
20b80 65 74 65 72 20 74 68 61 74 20 69 73 20 6c 65 73  eter that is les
20b90 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74 68  s restrictive th
20ba0 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69 65  an that specifie
20bb0 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20  d by.**     the 
20bc0 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e 20  flags passed in 
20bd0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
20be0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
20bf0 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
20c00 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c    <li> <b>cache<
20c10 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20  /b>: ^The cache 
20c20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
20c30 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22   set to either "
20c40 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20  shared" or.**   
20c50 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65    "private". ^Se
20c60 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61  tting it to "sha
20c70 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65  red" is equivale
20c80 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
20c90 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  e.**     SQLITE_
20ca0 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
20cb0 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67   bit in the flag
20cc0 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  s argument passe
20cd0 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69  d to.**     sqli
20ce0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e  te3_open_v2(). ^
20cf0 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68  Setting the cach
20d00 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22  e parameter to "
20d10 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20  private" is .** 
20d20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74      equivalent t
20d30 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51  o setting the SQ
20d40 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
20d50 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20  ECACHE bit..**  
20d60 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f     ^If sqlite3_o
20d70 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64  pen_v2() is used
20d80 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22   and the "cache"
20d90 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72   parameter is pr
20da0 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20  esent in.**     
20db0 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20  a URI filename, 
20dc0 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69  its value overri
20dd0 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 75  des any behaviou
20de0 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73  r requested by s
20df0 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51  etting.**     SQ
20e00 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
20e10 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45  ECACHE or SQLITE
20e20 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
20e30 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  E flag..** </ul>
20e40 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69  .**.** ^Specifyi
20e50 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61  ng an unknown pa
20e60 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71  rameter in the q
20e70 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
20e80 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61  f a URI is not a
20e90 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74  n.** error.  Fut
20ea0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
20eb0 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64  SQLite might und
20ec0 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e  erstand addition
20ed0 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61  al query.** para
20ee0 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71  meters.  See "[q
20ef0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20  uery parameters 
20f00 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61  with special mea
20f10 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22  ning to SQLite]"
20f20 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
20f30 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
20f40 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
20f50 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20  name examples]] 
20f60 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65  <h3>URI filename
20f70 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a   examples</h3>.*
20f80 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  *.** <table bord
20f90 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e  er="1" align=cen
20fa0 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d  ter cellpadding=
20fb0 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55  5>.** <tr><th> U
20fc0 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68  RI filenames <th
20fd0 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72  > Results.** <tr
20fe0 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
20ff0 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
21000 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69       Open the fi
21010 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20  le "data.db" in 
21020 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
21030 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  ctory..** <tr><t
21040 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72  d> file:/home/fr
21050 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a  ed/data.db<br>.*
21060 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
21070 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  ///home/fred/dat
21080 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20  a.db <br> .**   
21090 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f         file://lo
210a0 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65  calhost/home/fre
210b0 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c  d/data.db <br> <
210c0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
210d0 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   Open the databa
210e0 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  se file "/home/f
210f0 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a  red/data.db"..**
21100 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
21110 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66  /darkstar/home/f
21120 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e  red/data.db <td>
21130 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e   .**          An
21140 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61   error. "darksta
21150 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f  r" is not a reco
21160 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79  gnized authority
21170 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79  ..** <tr><td sty
21180 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a  le="white-space:
21190 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20  nowrap"> .**    
211a0 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a        file:///C:
211b0 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64  /Documents%20and
211c0 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64  %20Settings/fred
211d0 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62  /Desktop/data.db
211e0 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e  .**     <td> Win
211f0 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20  dows only: Open 
21200 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
21210 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73  b" on fred's des
21220 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a  ktop on drive.**
21230 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f            C:. No
21240 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20  te that the %20 
21250 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73  escaping in this
21260 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20   example is not 
21270 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20  strictly .**    
21280 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20        necessary 
21290 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65  - space characte
212a0 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c  rs can be used l
212b0 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20  iterally.**     
212c0 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65       in URI file
212d0 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  names..** <tr><t
212e0 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f  d> file:data.db?
212f0 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72  mode=ro&cache=pr
21300 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20  ivate <td> .**  
21310 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c          Open fil
21320 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
21330 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
21340 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e  tory for read-on
21350 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20  ly access..**   
21360 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73         Regardles
21370 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
21380 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65  not shared-cache
21390 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64   mode is enabled
213a0 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   by.**          
213b0 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70  default, use a p
213c0 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a  rivate cache..**
213d0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
213e0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
213f0 62 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63  b?vfs=unix-noloc
21400 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20  k <td>.**       
21410 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68     Open file "/h
21420 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
21430 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69  ". Use the speci
21440 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 6e 6f 6c  al VFS "unix-nol
21450 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ock"..** <tr><td
21460 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
21470 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64  ode=readonly <td
21480 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
21490 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e  n error. "readon
214a0 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c  ly" is not a val
214b0 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68  id option for th
214c0 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74  e "mode" paramet
214d0 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  er..** </table>.
214e0 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64  **.** ^URI hexad
214f0 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
21500 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72  quences (%HH) ar
21510 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68  e supported with
21520 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a  in the path and.
21530 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  ** query compone
21540 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20  nts of a URI. A 
21550 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
21560 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73  pe sequence cons
21570 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72  ists of a.** per
21580 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20  cent sign - "%" 
21590 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78  - followed by ex
215a0 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65  actly two hexade
215b0 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a  cimal digits .**
215c0 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f   specifying an o
215d0 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66  ctet value. ^Bef
215e0 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20  ore the path or 
215f0 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
21600 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c   of a.** URI fil
21610 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70  ename are interp
21620 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20  reted, they are 
21630 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54  encoded using UT
21640 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20  F-8 and all .** 
21650 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
21660 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70  pe sequences rep
21670 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c  laced by a singl
21680 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e  e byte containin
21690 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70  g the.** corresp
216a0 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66  onding octet. If
216b0 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65   this process ge
216c0 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c  nerates an inval
216d0 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  id UTF-8 encodin
216e0 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  g,.** the result
216f0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
21700 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
21710 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
21720 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
21730 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
21740 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
21750 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
21760 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
21770 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73  e3_open_v2() mus
21780 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
21790 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
217a0 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
217b0 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
217c0 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
217d0 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
217e0 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
217f0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
21800 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
21810 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
21820 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
21830 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
21840 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
21850 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
21860 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72  ows Runtime user
21870 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70  s:</b>  The temp
21880 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20  orary directory 
21890 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70  must be set.** p
218a0 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20  rior to calling 
218b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
218c0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
218d0 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  2().  Otherwise,
218e0 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74   various.** feat
218f0 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72  ures that requir
21900 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d  e the use of tem
21910 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79  porary files may
21920 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   fail..**.** See
21930 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
21940 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a  temp_directory].
21950 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  */.int sqlite3_o
21960 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  pen(.  const cha
21970 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
21980 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
21990 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
219a0 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
219b0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
219c0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
219d0 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  e */.);.int sqli
219e0 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f  te3_open16(.  co
219f0 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61  nst void *filena
21a00 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
21a10 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
21a20 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  16) */.  sqlite3
21a30 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
21a40 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
21a50 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
21a60 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
21a70 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  _v2(.  const cha
21a80 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
21a90 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
21aa0 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
21ab0 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c   sqlite3 **ppDb,
21ac0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
21ad0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
21ae0 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73  e */.  int flags
21af0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
21b00 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e  * Flags */.  con
21b10 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20  st char *zVfs   
21b20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
21b30 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73  VFS module to us
21b40 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
21b50 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
21b60 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50  Values For URI P
21b70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20  arameters.**.** 
21b80 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74  These are utilit
21b90 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66  y routines, usef
21ba0 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d  ul to VFS implem
21bb0 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20  entations, that 
21bc0 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20  check.** to see 
21bd0 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69  if a database fi
21be0 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61  le was a URI tha
21bf0 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70  t contained a sp
21c00 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a  ecific query .**
21c10 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20   parameter, and 
21c20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68  if so obtains th
21c30 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  e value of that 
21c40 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e  query parameter.
21c50 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74  .**.** If F is t
21c60 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
21c70 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73  name pointer pas
21c80 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
21c90 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a  en() method of .
21ca0 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65  ** a VFS impleme
21cb0 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65  ntation when the
21cc0 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
21cd0 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20   to xOpen() has 
21ce0 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20  one or .** more 
21cf0 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  of the [SQLITE_O
21d00 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c  PEN_URI] or [SQL
21d10 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
21d20 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a  ] bits set and.*
21d30 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20  * P is the name 
21d40 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72  of the query par
21d50 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  ameter, then.** 
21d60 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
21d70 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
21d80 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
21d90 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74  the P.** paramet
21da0 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20  er if it exists 
21db0 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
21dc0 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20  r if P does not 
21dd0 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20  appear as a .** 
21de0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
21df0 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61  on F.  If P is a
21e00 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
21e10 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20   of F.** has no 
21e20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20  explicit value, 
21e30 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
21e40 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
21e50 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69  returns.** a poi
21e60 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79  nter to an empty
21e70 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
21e80 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
21e90 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
21ea0 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68  utine assumes th
21eb0 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61  at P is a boolea
21ec0 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61  n.** parameter a
21ed0 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  nd returns true 
21ee0 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29  (1) or false (0)
21ef0 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68   according to th
21f00 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e  e value.** of P.
21f10 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72    The sqlite3_ur
21f20 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
21f30 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
21f40 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65   true (1) if the
21f50 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65  .** value of que
21f60 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
21f70 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20  s one of "yes", 
21f80 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20  "true", or "on" 
21f90 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f  in any.** case o
21fa0 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  r if the value b
21fb0 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e  egins with a non
21fc0 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54  -zero number.  T
21fd0 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  he .** sqlite3_u
21fe0 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
21ff0 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  ) routines retur
22000 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20  ns false (0) if 
22010 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  the value of.** 
22020 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
22030 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22  P is one of "no"
22040 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f  , "false", or "o
22050 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20  ff" in any case 
22060 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c  or.** if the val
22070 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
22080 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20   numeric zero.  
22090 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75  If P is not a qu
220a0 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
220b0 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20   on F or if the 
220c0 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f  value of P is do
220d0 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79  es not match any
220e0 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65   of the.** above
220f0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
22100 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
22110 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29  ) returns (B!=0)
22120 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
22130 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c  te3_uri_int64(F,
22140 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e  P,D) routine con
22150 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20  verts the value 
22160 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36  of P into a.** 6
22170 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
22180 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eger and returns
22190 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f   that integer, o
221a0 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  r D if P does no
221b0 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20  t.** exist.  If 
221c0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
221d0 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  s something othe
221e0 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65  r than an intege
221f0 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20  r, then.** zero 
22200 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
22210 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55  .** If F is a NU
22220 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
22230 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
22240 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
22250 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20  rns NULL and.** 
22260 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
22270 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
22280 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e  ns B.  If F is n
22290 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ot a NULL pointe
222a0 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20  r and.** is not 
222b0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
222c0 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72  pathname pointer
222d0 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73   that SQLite pas
222e0 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
222f0 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64  en.** VFS method
22300 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
22310 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ior of this rout
22320 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ine is undefined
22330 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a   and probably.**
22340 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f   undesirable..*/
22350 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
22360 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
22370 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  er(const char *z
22380 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20  Filename, const 
22390 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69  char *zParam);.i
223a0 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  nt sqlite3_uri_b
223b0 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61  oolean(const cha
223c0 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20  r *zFile, const 
223d0 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e  char *zParam, in
223e0 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c  t bDefault);.sql
223f0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
22400 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e  e3_uri_int64(con
22410 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20  st char*, const 
22420 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69  char*, sqlite3_i
22430 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt64);.../*.** C
22440 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43  API3REF: Error C
22450 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65  odes And Message
22460 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
22470 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
22480 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
22490 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65   the numeric [re
224a0 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  sult code] or.**
224b0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
224c0 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  t code] for the 
224d0 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c  most recent fail
224e0 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49  ed sqlite3_* API
224f0 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61   call.** associa
22500 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61  ted with a [data
22510 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
22520 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49  . If a prior API
22530 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20   call failed.** 
22540 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  but the most rec
22550 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63  ent API call suc
22560 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75  ceeded, the retu
22570 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a  rn value from.**
22580 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
22590 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
225a0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65    ^The sqlite3_e
225b0 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
225c0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
225d0 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70  s the same excep
225e0 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73  t that it always
225f0 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a   returns the .**
22600 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
22610 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65  t code] even whe
22620 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  n extended resul
22630 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64  t codes are.** d
22640 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  isabled..**.** ^
22650 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  The sqlite3_errm
22660 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  sg() and sqlite3
22670 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75  _errmsg16() retu
22680 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  rn English-langu
22690 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74  age.** text that
226a0 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
226b0 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20  rror, as either 
226c0 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
226d0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
226e0 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c   ^(Memory to hol
226f0 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  d the error mess
22700 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61  age string is ma
22710 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  naged internally
22720 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
22730 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65  tion does not ne
22740 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75  ed to worry abou
22750 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65  t freeing the re
22760 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  sult..** However
22770 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69  , the error stri
22780 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72  ng might be over
22790 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c  written or deall
227a0 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62  ocated by.** sub
227b0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
227c0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
227d0 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e  terface function
227e0 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s.)^.**.** ^The 
227f0 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29  sqlite3_errstr()
22800 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
22810 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c  ns the English-l
22820 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20  anguage text.** 
22830 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
22840 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  he [result code]
22850 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e  , as UTF-8..** ^
22860 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
22870 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
22880 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
22890 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a  ged internally.*
228a0 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62  * and must not b
228b0 65 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61  e freed by the a
228c0 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a  pplication)^..**
228d0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72  .** When the ser
228e0 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
228f0 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75  ng mode] is in u
22900 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20  se, it might be 
22910 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74  the.** case that
22920 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20   a second error 
22930 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61  occurs on a sepa
22940 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62  rate thread in b
22950 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69  etween.** the ti
22960 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  me of the first 
22970 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61  error and the ca
22980 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  ll to these inte
22990 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20  rfaces..** When 
229a0 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68  that happens, th
229b0 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77  e second error w
229c0 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20  ill be reported 
229d0 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69  since these.** i
229e0 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73  nterfaces always
229f0 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74   report the most
22a00 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20   recent result. 
22a10 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69   To avoid.** thi
22a20 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63  s, each thread c
22a30 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73  an obtain exclus
22a40 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  ive use of the [
22a50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
22a60 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76  ion] D.** by inv
22a70 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
22a80 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c  utex_enter]([sql
22a90 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
22aa0 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e  )) before beginn
22ab0 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20  ing.** to use D 
22ac0 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71  and invoking [sq
22ad0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
22ae0 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  e]([sqlite3_db_m
22af0 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a  utex](D)) after.
22b00 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20  ** all calls to 
22b10 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c  the interfaces l
22b20 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63  isted here are c
22b30 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ompleted..**.** 
22b40 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20  If an interface 
22b50 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54  fails with SQLIT
22b60 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d  E_MISUSE, that m
22b70 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61  eans the interfa
22b80 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65  ce.** was invoke
22b90 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79  d incorrectly by
22ba0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
22bb0 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c  .  In that case,
22bc0 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f   the.** error co
22bd0 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d  de and message m
22be0 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65  ay or may not be
22bf0 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c   set..*/.int sql
22c00 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c  ite3_errcode(sql
22c10 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73  ite3 *db);.int s
22c20 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
22c30 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
22c40 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  *db);.const char
22c50 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
22c60 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73  (sqlite3*);.cons
22c70 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
22c80 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33  errmsg16(sqlite3
22c90 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  *);.const char *
22ca0 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69  sqlite3_errstr(i
22cb0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
22cc0 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d  3REF: SQL Statem
22cd0 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  ent Object.** KE
22ce0 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65  YWORDS: {prepare
22cf0 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72  d statement} {pr
22d00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22d10 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  s}.**.** An inst
22d20 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
22d30 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
22d40 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74   single SQL stat
22d50 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f  ement..** This o
22d60 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73  bject is various
22d70 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70  ly known as a "p
22d80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22d90 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70  t" or a.** "comp
22da0 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  iled SQL stateme
22db0 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73  nt" or simply as
22dc0 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a   a "statement"..
22dd0 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f  **.** The life o
22de0 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62  f a statement ob
22df0 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68  ject goes someth
22e00 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ing like this:.*
22e10 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
22e20 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a  > Create the obj
22e30 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
22e40 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
22e50 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a   or a related.**
22e60 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a        function..
22e70 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c  ** <li> Bind val
22e80 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72  ues to [host par
22e90 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74  ameters] using t
22ea0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
22eb0 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65  *().**      inte
22ec0 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20  rfaces..** <li> 
22ed0 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63  Run the SQL by c
22ee0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
22ef0 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d  step()] one or m
22f00 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
22f10 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61  i> Reset the sta
22f20 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
22f30 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
22f40 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20  hen go back.**  
22f50 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20      to step 2.  
22f60 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20  Do this zero or 
22f70 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
22f80 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20  li> Destroy the 
22f90 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
22fa0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
22fb0 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a  ]..** </ol>.**.*
22fc0 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d  * Refer to docum
22fd0 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69  entation on indi
22fe0 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61  vidual methods a
22ff0 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f  bove for additio
23000 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
23010 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  on..*/.typedef s
23020 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74  truct sqlite3_st
23030 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b  mt sqlite3_stmt;
23040 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
23050 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74  : Run-time Limit
23060 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69  s.**.** ^(This i
23070 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20  nterface allows 
23080 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69  the size of vari
23090 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74  ous constructs t
230a0 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20  o be limited.** 
230b0 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  on a connection 
230c0 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61  by connection ba
230d0 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20  sis.  The first 
230e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
230f0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
23100 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20  nnection] whose 
23110 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73  limit is to be s
23120 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20  et or queried.  
23130 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
23140 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f  rameter is one o
23150 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74  f the [limit cat
23160 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65  egories] that de
23170 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20  fine a.** class 
23180 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  of constructs to
23190 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64   be size limited
231a0 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72  .  The third par
231b0 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
231c0 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74   new limit for t
231d0 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e  hat construct.)^
231e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
231f0 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65  ew limit is a ne
23200 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74  gative number, t
23210 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68  he limit is unch
23220 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20  anged..** ^(For 
23230 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67  each limit categ
23240 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ory SQLITE_LIMIT
23250 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65  _<i>NAME</i> the
23260 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d  re is a .** [lim
23270 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72  its | hard upper
23280 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61   bound].** set a
23290 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62  t compile-time b
232a0 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73  y a C preprocess
232b0 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a  or macro called.
232c0 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c  ** [limits | SQL
232d0 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c  ITE_MAX_<i>NAME<
232e0 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f  /i>]..** (The "_
232f0 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e  LIMIT_" in the n
23300 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74  ame is changed t
23310 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a  o "_MAX_".))^.**
23320 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e   ^Attempts to in
23330 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61  crease a limit a
23340 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70  bove its hard up
23350 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a  per bound are.**
23360 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61   silently trunca
23370 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20  ted to the hard 
23380 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a  upper bound..**.
23390 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f  ** ^Regardless o
233a0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
233b0 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63   the limit was c
233c0 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20  hanged, the .** 
233d0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
233e0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
233f0 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61  rns the prior va
23400 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74  lue of the limit
23410 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20  ..** ^Hence, to 
23420 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74  find the current
23430 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69   value of a limi
23440 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69  t without changi
23450 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79  ng it,.** simply
23460 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74   invoke this int
23470 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20  erface with the 
23480 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
23490 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a  set to -1..**.**
234a0 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73   Run-time limits
234b0 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
234c0 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61  r use in applica
234d0 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67  tions that manag
234e0 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20  e.** both their 
234f0 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  own internal dat
23500 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64  abase and also d
23510 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72  atabases that ar
23520 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20  e controlled.** 
23530 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74  by untrusted ext
23540 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20  ernal sources.  
23550 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69  An example appli
23560 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20  cation might be 
23570 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72  a.** web browser
23580 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77   that has its ow
23590 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20  n databases for 
235a0 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20  storing history 
235b0 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20  and.** separate 
235c0 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f  databases contro
235d0 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69  lled by JavaScri
235e0 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  pt applications 
235f0 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66  downloaded.** of
23600 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20  f the Internet. 
23610 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61   The internal da
23620 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67  tabases can be g
23630 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67  iven the.** larg
23640 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74  e, default limit
23650 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61  s.  Databases ma
23660 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61  naged by externa
23670 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a  l sources can.**
23680 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73   be given much s
23690 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65  maller limits de
236a0 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e  signed to preven
236b0 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65  t a denial of se
236c0 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e  rvice.** attack.
236d0 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67    Developers mig
236e0 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20  ht also want to 
236f0 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  use the [sqlite3
23700 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
23710 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  )].** interface 
23720 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72  to further contr
23730 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c  ol untrusted SQL
23740 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
23750 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
23760 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74  reated by an unt
23770 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61  rusted script ca
23780 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75  n be contained u
23790 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78  sing the.** [max
237a0 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
237b0 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  AGMA]..**.** New
237c0 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20   run-time limit 
237d0 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62  categories may b
237e0 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
237f0 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69  e releases..*/.i
23800 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  nt sqlite3_limit
23810 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69  (sqlite3*, int i
23820 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a  d, int newVal);.
23830 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23840 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20   Run-Time Limit 
23850 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45  Categories.** KE
23860 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63  YWORDS: {limit c
23870 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74  ategory} {*limit
23880 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a   categories}.**.
23890 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
238a0 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75  ts define variou
238b0 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69  s performance li
238c0 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  mits.** that can
238d0 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72   be lowered at r
238e0 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73  un-time using [s
238f0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e  qlite3_limit()].
23900 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73  .** The synopsis
23910 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73   of the meanings
23920 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20   of the various 
23930 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20  limits is shown 
23940 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69  below..** Additi
23950 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
23960 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74   is available at
23970 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74   [limits | Limit
23980 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a  s in SQLite]..**
23990 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
239a0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
239b0 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
239c0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64  _LIMIT_LENGTH</d
239d0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
239e0 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e  ximum size of an
239f0 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  y string or BLOB
23a00 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69   or table row, i
23a10 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a  n bytes.<dd>)^.*
23a20 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
23a30 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d  MIT_SQL_LENGTH]]
23a40 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
23a50 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
23a60 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
23a70 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
23a80 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
23a90 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64  t, in bytes.</dd
23aa0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
23ab0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d  TE_LIMIT_COLUMN]
23ac0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
23ad0 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e  IMIT_COLUMN</dt>
23ae0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
23af0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
23b00 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65  lumns in a table
23b10 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69   definition or i
23b20 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  n the.** result 
23b30 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
23b40 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d  ] or the maximum
23b50 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
23b60 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a  ns in an index.*
23b70 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52  * or in an ORDER
23b80 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20   BY or GROUP BY 
23b90 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a  clause.</dd>)^.*
23ba0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
23bb0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d  MIT_EXPR_DEPTH]]
23bc0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
23bd0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f  MIT_EXPR_DEPTH</
23be0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
23bf0 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
23c00 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f  the parse tree o
23c10 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e  n any expression
23c20 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
23c30 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
23c40 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20  MPOUND_SELECT]] 
23c50 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
23c60 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
23c70 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  CT</dt>.** <dd>T
23c80 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
23c90 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20  r of terms in a 
23ca0 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20  compound SELECT 
23cb0 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29  statement.</dd>)
23cc0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
23cd0 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d  _LIMIT_VDBE_OP]]
23ce0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
23cf0 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e  MIT_VDBE_OP</dt>
23d00 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
23d10 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e  mum number of in
23d20 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20  structions in a 
23d30 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
23d40 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20  program.** used 
23d50 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20  to implement an 
23d60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
23d70 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f  This limit is no
23d80 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65  t currently.** e
23d90 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20  nforced, though 
23da0 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 61 64  that might be ad
23db0 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ded in some futu
23dc0 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a  re release of.**
23dd0 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a   SQLite.</dd>)^.
23de0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
23df0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
23e00 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  G]] ^(<dt>SQLITE
23e10 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
23e20 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ARG</dt>.** <dd>
23e30 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
23e40 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
23e50 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f  on a function.</
23e60 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
23e70 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
23e80 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  HED]] ^(<dt>SQLI
23e90 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
23ea0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
23eb0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
23ec0 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74   of [ATTACH | at
23ed0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
23ee0 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
23ef0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
23f00 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
23f10 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  TH]].** ^(<dt>SQ
23f20 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
23f30 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f  PATTERN_LENGTH</
23f40 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
23f50 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
23f60 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67   the pattern arg
23f70 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49  ument to the [LI
23f80 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d  KE] or.** [GLOB]
23f90 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e   operators.</dd>
23fa0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
23fb0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
23fc0 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c  _NUMBER]].** ^(<
23fd0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
23fe0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c  VARIABLE_NUMBER<
23ff0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
24000 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75  maximum index nu
24010 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72  mber of any [par
24020 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51  ameter] in an SQ
24030 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a  L statement.)^.*
24040 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
24050 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
24060 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
24070 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
24080 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
24090 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
240a0 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20  th of recursion 
240b0 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64  for triggers.</d
240c0 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  d>)^.** </dl>.*/
240d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
240e0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20  LIMIT_LENGTH    
240f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
24100 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
24110 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
24120 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
24130 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
24140 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20  E_LIMIT_COLUMN  
24150 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
24160 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
24170 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
24180 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  PTH             
24190 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
241a0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
241b0 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  ND_SELECT       
241c0 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
241d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
241e0 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20  OP              
241f0 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
24200 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
24210 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20  TION_ARG        
24220 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
24230 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
24240 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20  ACHED           
24250 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
24260 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49   SQLITE_LIMIT_LI
24270 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
24280 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e  H       8.#defin
24290 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
242a0 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20  ARIABLE_NUMBER  
242b0 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69           9.#defi
242c0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
242d0 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20  TRIGGER_DEPTH   
242e0 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a           10../*.
242f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
24300 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74  piling An SQL St
24310 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f  atement.** KEYWO
24320 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d  RDS: {SQL statem
24330 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a  ent compiler}.**
24340 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61  .** To execute a
24350 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20  n SQL query, it 
24360 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f  must first be co
24370 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79  mpiled into a by
24380 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72  te-code.** progr
24390 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20  am using one of 
243a0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
243b0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
243c0 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20  argument, "db", 
243d0 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  is a [database c
243e0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69  onnection] obtai
243f0 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72  ned from a.** pr
24400 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
24410 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
24420 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
24430 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a  3_open_v2()] or.
24440 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
24450 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61  16()].  The data
24460 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
24470 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65  must not have be
24480 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  en closed..**.**
24490 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
244a0 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73  ment, "zSql", is
244b0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
244c0 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65  o be compiled, e
244d0 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74  ncoded.** as eit
244e0 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
244f0 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65  -16.  The sqlite
24500 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20  3_prepare() and 
24510 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
24520 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  v2().** interfac
24530 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e  es use UTF-8, an
24540 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
24550 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65  e16() and sqlite
24560 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
24570 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a  .** use UTF-16..
24580 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42  **.** ^If the nB
24590 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  yte argument is 
245a0 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20  less than zero, 
245b0 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61  then zSql is rea
245c0 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66  d up to the.** f
245d0 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
245e0 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20  ator. ^If nByte 
245f0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
24600 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20   then it is the 
24610 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65  maximum.** numbe
24620 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 64  r of  bytes read
24630 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68   from zSql.  ^Wh
24640 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  en nByte is non-
24650 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a  negative, the.**
24660 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64   zSql string end
24670 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20  s at either the 
24680 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20  first '\000' or 
24690 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74  '\u0000' charact
246a0 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79  er or.** the nBy
246b0 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63  te-th byte, whic
246c0 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73  hever comes firs
246d0 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72  t. If the caller
246e0 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74   knows.** that t
246f0 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69  he supplied stri
24700 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e  ng is nul-termin
24710 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65  ated, then there
24720 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70   is a small.** p
24730 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e  erformance advan
24740 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65  tage to be gaine
24750 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20  d by passing an 
24760 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20  nByte parameter 
24770 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c  that.** is equal
24780 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   to the number o
24790 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69  f bytes in the i
247a0 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69  nput string <i>i
247b0 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20  ncluding</i>.** 
247c0 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  the nul-terminat
247d0 6f 72 20 62 79 74 65 73 20 61 73 20 74 68 69 73  or bytes as this
247e0 20 73 61 76 65 73 20 53 51 4c 69 74 65 20 66 72   saves SQLite fr
247f0 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a 2a 20  om having to.** 
24800 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74  make a copy of t
24810 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e  he input string.
24820 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69  .**.** ^If pzTai
24830 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68  l is not NULL th
24840 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61  en *pzTail is ma
24850 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74  de to point to t
24860 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a  he first byte.**
24870 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66   past the end of
24880 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73   the first SQL s
24890 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
248a0 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
248b0 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c  s only.** compil
248c0 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74  e the first stat
248d0 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73  ement in zSql, s
248e0 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66  o *pzTail is lef
248f0 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a  t pointing to.**
24900 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e   what remains un
24910 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  compiled..**.** 
24920 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74  ^*ppStmt is left
24930 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63   pointing to a c
24940 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65  ompiled [prepare
24950 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
24960 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63  t can be.** exec
24970 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  uted using [sqli
24980 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49  te3_step()].  ^I
24990 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72  f there is an er
249a0 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20  ror, *ppStmt is 
249b0 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20  set.** to NULL. 
249c0 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74   ^If the input t
249d0 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20  ext contains no 
249e0 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75  SQL (if the inpu
249f0 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a  t is an empty.**
24a00 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d   string or a com
24a10 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74  ment) then *ppSt
24a20 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c  mt is set to NUL
24a30 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e  L..** The callin
24a40 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72  g procedure is r
24a50 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64  esponsible for d
24a60 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70  eleting the comp
24a70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74  iled.** SQL stat
24a80 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
24a90 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
24aa0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
24ab0 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a  nished with it..
24ac0 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f  ** ppStmt may no
24ad0 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  t be NULL..**.**
24ae0 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68   ^On success, th
24af0 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
24b00 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f  e() family of ro
24b10 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
24b20 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74  QLITE_OK];.** ot
24b30 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
24b40 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
24b50 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
24b60 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
24b70 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  2() and sqlite3_
24b80 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69  prepare16_v2() i
24b90 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a  nterfaces are.**
24ba0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
24bb0 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d   all new program
24bc0 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72  s. The two older
24bd0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
24be0 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20  retained.** for 
24bf0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
24c00 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65  ibility, but the
24c10 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75  ir use is discou
24c20 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68  raged..** ^In th
24c30 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
24c40 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20  s, the prepared 
24c50 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61  statement.** tha
24c60 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74  t is returned (t
24c70 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
24c80 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69  ] object) contai
24c90 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ns a copy of the
24ca0 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c  .** original SQL
24cb0 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73   text. This caus
24cc0 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  es the [sqlite3_
24cd0 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63  step()] interfac
24ce0 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64  e to.** behave d
24cf0 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68  ifferently in th
24d00 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ree ways:.**.** 
24d10 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  <ol>.** <li>.** 
24d20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65  ^If the database
24d30 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c   schema changes,
24d40 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75   instead of retu
24d50 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43  rning [SQLITE_SC
24d60 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61  HEMA] as it.** a
24d70 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f  lways used to do
24d80 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
24d90 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69  )] will automati
24da0 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20  cally recompile 
24db0 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65  the SQL.** state
24dc0 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20  ment and try to 
24dd0 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 0a 2a 2a  run it again..**
24de0 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
24df0 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72  >.** ^When an er
24e00 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c  ror occurs, [sql
24e10 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
24e20 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  l return one of 
24e30 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20  the detailed.** 
24e40 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72  [error codes] or
24e50 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
24e60 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c   codes].  ^The l
24e70 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77  egacy behavior w
24e80 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69  as that.** [sqli
24e90 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c  te3_step()] woul
24ea0 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20  d only return a 
24eb0 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f  generic [SQLITE_
24ec0 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f  ERROR] result co
24ed0 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70  de.** and the ap
24ee0 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20  plication would 
24ef0 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73  have to make a s
24f00 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73  econd call to [s
24f10 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a  qlite3_reset()].
24f20 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  ** in order to f
24f30 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ind the underlyi
24f40 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20  ng cause of the 
24f50 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68  problem. With th
24f60 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a  e "v2" prepare.*
24f70 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  * interfaces, th
24f80 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61  e underlying rea
24f90 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f  son for the erro
24fa0 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  r is returned im
24fb0 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f  mediately..** </
24fc0 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
24fd0 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66  * ^If the specif
24fe0 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74  ic value bound t
24ff0 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68  o [parameter | h
25000 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69  ost parameter] i
25010 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20  n the .** WHERE 
25020 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66  clause might inf
25030 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63  luence the choic
25040 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
25050 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  for a statement,
25060 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61  .** then the sta
25070 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61  tement will be a
25080 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
25090 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74  ompiled, as if t
250a0 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a  here had been .*
250b0 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  * a schema chang
250c0 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20  e, on the first 
250d0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
250e0 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67  ] call following
250f0 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74   any change.** t
25100 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  o the [sqlite3_b
25110 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69  ind_text | bindi
25120 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61  ngs] of that [pa
25130 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54  rameter]. .** ^T
25140 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75  he specific valu
25150 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73  e of WHERE-claus
25160 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69  e [parameter] mi
25170 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
25180 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20  e .** choice of 
25190 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68  query plan if th
251a0 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  e parameter is t
251b0 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64  he left-hand sid
251c0 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a  e of a [LIKE].**
251d0 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61   or [GLOB] opera
251e0 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61  tor or if the pa
251f0 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61  rameter is compa
25200 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65  red to an indexe
25210 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20  d column.** and 
25220 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  the [SQLITE_ENAB
25230 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c  LE_STAT3] compil
25240 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
25250 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 68 65   enabled..** the
25260 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f   .** </li>.** </
25270 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ol>.*/.int sqlit
25280 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71  e3_prepare(.  sq
25290 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
252a0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
252b0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
252c0 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
252d0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
252e0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
252f0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
25300 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
25310 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
25320 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
25330 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
25340 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
25350 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
25360 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
25370 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
25380 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
25390 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
253a0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
253b0 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
253c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
253d0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
253e0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
253f0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
25400 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
25410 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
25420 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
25430 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
25440 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
25450 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
25460 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
25470 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
25480 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
25490 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
254a0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
254b0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
254c0 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
254d0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
254e0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
254f0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
25500 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
25510 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33  are16(.  sqlite3
25520 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
25530 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
25540 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
25550 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
25560 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
25570 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
25580 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
25590 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
255a0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
255b0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
255c0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
255d0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
255e0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
255f0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
25600 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
25610 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
25620 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
25630 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
25640 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
25650 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a  3_prepare16_v2(.
25660 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
25670 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
25680 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
25690 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
256a0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
256b0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
256c0 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
256d0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
256e0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
256f0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
25700 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
25710 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
25720 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
25730 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
25740 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
25750 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
25760 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
25770 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
25780 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a   of zSql */.);..
25790 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
257a0 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65  Retrieving State
257b0 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e  ment SQL.**.** ^
257c0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
257d0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
257e0 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63  trieve a saved c
257f0 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69  opy of the origi
25800 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20  nal.** SQL text 
25810 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61  used to create a
25820 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
25830 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74  ment] if that st
25840 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63  atement was.** c
25850 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69  ompiled using ei
25860 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
25870 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
25880 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
25890 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  6_v2()]..*/.cons
258a0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
258b0 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  sql(sqlite3_stmt
258c0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
258d0 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
258e0 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
258f0 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20  tatement Writes 
25900 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a  The Database.**.
25910 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
25920 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29  stmt_readonly(X)
25930 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
25940 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
25950 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c  o) if.** and onl
25960 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72  y if the [prepar
25970 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20  ed statement] X 
25980 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20  makes no direct 
25990 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68  changes to.** th
259a0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
259b0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a   database file..
259c0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
259d0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
259e0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
259f0 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75  ns] or.** [virtu
25a00 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74  al tables] might
25a10 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
25a20 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20  base indirectly 
25a30 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74  as a side effect
25a40 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .  .** ^(For exa
25a50 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c  mple, if an appl
25a60 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20  ication defines 
25a70 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c  a function "eval
25a80 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c  ()" that .** cal
25a90 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ls [sqlite3_exec
25aa0 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  ()], then the fo
25ab0 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74  llowing SQL stat
25ac0 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63  ement would.** c
25ad0 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
25ae0 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20  se file through 
25af0 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a  side-effects:.**
25b00 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
25b10 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45  <pre>.**    SELE
25b20 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20  CT eval('DELETE 
25b30 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74  FROM t1') FROM t
25b40 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  2;.** </pre></bl
25b50 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
25b60 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20  But because the 
25b70 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
25b80 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nt does not chan
25b90 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
25ba0 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79  file.** directly
25bb0 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  , sqlite3_stmt_r
25bc0 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20  eadonly() would 
25bd0 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75  still return tru
25be0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e  e.)^.**.** ^Tran
25bf0 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20  saction control 
25c00 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20  statements such 
25c10 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d  as [BEGIN], [COM
25c20 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d  MIT], [ROLLBACK]
25c30 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d  ,.** [SAVEPOINT]
25c40 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20  , and [RELEASE] 
25c50 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74  cause sqlite3_st
25c60 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
25c70 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a   return true,.**
25c80 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65   since the state
25c90 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73  ments themselves
25ca0 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79   do not actually
25cb0 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
25cc0 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68  base but.** rath
25cd0 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20  er they control 
25ce0 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68  the timing of wh
25cf0 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65  en other stateme
25d00 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a  nts modify the .
25d10 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54  ** database.  ^T
25d20 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20  he [ATTACH] and 
25d30 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65  [DETACH] stateme
25d40 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a  nts also cause.*
25d50 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  * sqlite3_stmt_r
25d60 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
25d70 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20  urn true since, 
25d80 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74  while those stat
25d90 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65  ements.** change
25da0 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
25db0 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65  on of a database
25dc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65   connection, the
25dd0 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a  y do not make .*
25de0 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  * changes to the
25df0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
25e00 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f  database files o
25e10 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73  n disk..*/.int s
25e20 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
25e30 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  only(sqlite3_stm
25e40 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
25e50 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
25e60 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70 61  rmine If A Prepa
25e70 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61  red Statement Ha
25e80 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 0a  s Been Reset.**.
25e90 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
25ea0 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74  stmt_busy(S) int
25eb0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
25ec0 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69  rue (non-zero) i
25ed0 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  f the.** [prepar
25ee0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
25ef0 68 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64  has been stepped
25f00 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75   at least once u
25f10 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
25f20 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68  3_step(S)] but h
25f30 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20 63 6f  as not run to co
25f40 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f 72 20  mpletion and/or 
25f50 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e  has not .** been
25f60 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71   reset using [sq
25f70 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e  lite3_reset(S)].
25f80 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
25f90 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69  tmt_busy(S).** i
25fa0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
25fb0 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 61   false if S is a
25fc0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
25fd0 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a  If S is not a .*
25fe0 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  * NULL pointer a
25ff0 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e  nd is not a poin
26000 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b  ter to a valid [
26010 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26020 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74  nt].** object, t
26030 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
26040 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
26050 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73  d probably undes
26060 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  irable..**.** Th
26070 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
26080 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62   be used in comb
26090 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33  ination [sqlite3
260a0 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a  _next_stmt()].**
260b0 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70   to locate all p
260c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
260d0 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ts associated wi
260e0 74 68 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a  th a database .*
260f0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  * connection tha
26100 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66  t are in need of
26110 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54   being reset.  T
26120 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c  his can be used,
26130 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  .** for example,
26140 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72   in diagnostic r
26150 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63  outines to searc
26160 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a  h for prepared .
26170 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  ** statements th
26180 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61  at are holding a
26190 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65   transaction ope
261a0 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
261b0 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69  3_stmt_busy(sqli
261c0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
261d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e  ** CAPI3REF: Dyn
261e0 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56  amically Typed V
261f0 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  alue Object.** K
26200 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63  EYWORDS: {protec
26210 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
26220 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20  e} {unprotected 
26230 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a  sqlite3_value}.*
26240 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
26250 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
26260 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70  ue object to rep
26270 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65  resent all value
26280 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
26290 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74   stored in a dat
262a0 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c  abase table. SQL
262b0 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
262c0 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74   typing.** for t
262d0 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f  he values it sto
262e0 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74  res.  ^Values st
262f0 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f  ored in sqlite3_
26300 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a  value objects.**
26310 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73   can be integers
26320 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  , floating point
26330 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73   values, strings
26340 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c  , BLOBs, or NULL
26350 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74  ..**.** An sqlit
26360 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
26370 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70  may be either "p
26380 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e  rotected" or "un
26390 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53  protected"..** S
263a0 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72  ome interfaces r
263b0 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74  equire a protect
263c0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
263d0 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61  .  Other interfa
263e0 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65  ces.** will acce
263f0 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74  pt either a prot
26400 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72  ected or an unpr
26410 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
26420 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20  value..** Every 
26430 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
26440 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76  ccepts sqlite3_v
26450 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73  alue arguments s
26460 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74  pecifies.** whet
26470 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65  her or not it re
26480 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74  quires a protect
26490 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
264a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d  ..**.** The term
264b0 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e  s "protected" an
264c0 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20  d "unprotected" 
264d0 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72  refer to whether
264e0 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74   or not.** a mut
264f0 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20  ex is held.  An 
26500 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69  internal mutex i
26510 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f  s held for a pro
26520 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
26530 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62  3_value object b
26540 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68  ut no mutex is h
26550 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f  eld for an unpro
26560 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
26570 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20  3_value object. 
26580 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
26590 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e  mpiled to be sin
265a0 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  gle-threaded.** 
265b0 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48  (with [SQLITE_TH
265c0 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20  READSAFE=0] and 
265d0 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68  with [sqlite3_th
265e0 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75  readsafe()] retu
265f0 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69  rning 0).** or i
26600 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20  f SQLite is run 
26610 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65  in one of reduce
26620 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a  d mutex modes .*
26630 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
26640 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f  _SINGLETHREAD] o
26650 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
26660 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a  _MULTITHREAD].**
26670 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e   then there is n
26680 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  o distinction be
26690 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
266a0 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
266b0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
266c0 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65   objects and the
266d0 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  y can be used in
266e0 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20  terchangeably.  
266f0 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20  However,.** for 
26700 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72  maximum code por
26710 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72  tability it is r
26720 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
26730 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
26740 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64  still make the d
26750 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
26760 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
26770 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
26780 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
26790 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20  jects even when 
267a0 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71  not strictly req
267b0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  uired..**.** ^Th
267c0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
267d0 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65  objects that are
267e0 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d   passed as param
267f0 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a  eters into the.*
26800 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
26810 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   of [application
26820 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
26830 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74  ctions] are prot
26840 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  ected..** ^The s
26850 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
26860 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
26870 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
26880 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
26890 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55  nprotected..** U
268a0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
268b0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
268c0 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
268d0 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74  d with.** [sqlit
268e0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
268f0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
26900 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  bind_value()]..*
26910 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  * The [sqlite3_v
26920 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  alue_blob | sqli
26930 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29  te3_value_type()
26940 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69  ] family of.** i
26950 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
26960 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  e protected sqli
26970 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
26980 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
26990 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33  ruct Mem sqlite3
269a0 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
269b0 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e  API3REF: SQL Fun
269c0 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62  ction Context Ob
269d0 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ject.**.** The c
269e0 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20  ontext in which 
269f0 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
26a00 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72  executes is stor
26a10 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ed in an.** sqli
26a20 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
26a30 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20  ct.  ^A pointer 
26a40 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f  to an sqlite3_co
26a50 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20  ntext object.** 
26a60 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20  is always first 
26a70 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70  parameter to [ap
26a80 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
26a90 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
26aa0 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
26ab0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
26ac0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
26ad0 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61  entation will pa
26ae0 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74  ss this.** point
26af0 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20  er through into 
26b00 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
26b10 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73  3_result_int | s
26b20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d  qlite3_result()]
26b30 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67  ,.** [sqlite3_ag
26b40 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
26b50 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  )], [sqlite3_use
26b60 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73  r_data()],.** [s
26b70 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
26b80 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71  b_handle()], [sq
26b90 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
26ba0 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20  a()],.** and/or 
26bb0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
26bc0 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  data()]..*/.type
26bd0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
26be0 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74  e3_context sqlit
26bf0 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a  e3_context;../*.
26c00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e  ** CAPI3REF: Bin
26c10 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50  ding Values To P
26c20 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
26c30 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ts.** KEYWORDS: 
26c40 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d  {host parameter}
26c50 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
26c60 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  s} {host paramet
26c70 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57  er name}.** KEYW
26c80 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d  ORDS: {SQL param
26c90 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d  eter} {SQL param
26ca0 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65  eters} {paramete
26cb0 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a  r binding}.**.**
26cc0 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74   ^(In the SQL st
26cd0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70  atement text inp
26ce0 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ut to [sqlite3_p
26cf0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
26d00 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a   its variants,.*
26d10 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62  * literals may b
26d20 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  e replaced by a 
26d30 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74  [parameter] that
26d40 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20   matches one of 
26d50 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d  following.** tem
26d60 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  plates:.**.** <u
26d70 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a  l>.** <li>  ?.**
26d80 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c   <li>  ?NNN.** <
26d90 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69  li>  :VVV.** <li
26da0 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  @VVV.** <li> 
26db0 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a   $VVV.** </ul>.*
26dc0 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70  *.** In the temp
26dd0 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e  lates above, NNN
26de0 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69   represents an i
26df0 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a  nteger literal,.
26e00 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65  ** and VVV repre
26e10 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75  sents an alphanu
26e20 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72  meric identifier
26e30 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  .)^  ^The values
26e40 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72   of these.** par
26e50 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61  ameters (also ca
26e60 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d  lled "host param
26e70 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22  eter names" or "
26e80 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29  SQL parameters")
26e90 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75  .** can be set u
26ea0 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
26eb0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
26ec0 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  es defined here.
26ed0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
26ee0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
26ef0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
26f00 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61  () routines is a
26f10 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  lways.** a point
26f20 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
26f30 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20  e3_stmt] object 
26f40 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a  returned from.**
26f50 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
26f60 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76  e_v2()] or its v
26f70 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ariants..**.** ^
26f80 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
26f90 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
26fa0 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61   of the SQL para
26fb0 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e  meter to be set.
26fc0 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  .** ^The leftmos
26fd0 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  t SQL parameter 
26fe0 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
26ff0 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61  1.  ^When the sa
27000 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20  me named.** SQL 
27010 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65  parameter is use
27020 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  d more than once
27030 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  , second and sub
27040 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72  sequent.** occur
27050 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20  rences have the 
27060 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68  same index as th
27070 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e  e first occurren
27080 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65  ce..** ^The inde
27090 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61  x for named para
270a0 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f  meters can be lo
270b0 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68  oked up using th
270c0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  e.** [sqlite3_bi
270d0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
270e0 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73  ex()] API if des
270f0 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65  ired.  ^The inde
27100 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20  x.** for "?NNN" 
27110 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68  parameters is th
27120 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a  e value of NNN..
27130 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75  ** ^The NNN valu
27140 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65  e must be betwee
27150 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c  n 1 and the [sql
27160 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
27170 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49   parameter [SQLI
27180 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
27190 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75  E_NUMBER] (defau
271a0 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a  lt value: 999)..
271b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
271c0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
271d0 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74   value to bind t
271e0 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  o the parameter.
271f0 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73  .**.** ^(In thos
27200 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  e routines that 
27210 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72  have a fourth ar
27220 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75  gument, its valu
27230 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
27240 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
27250 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  he parameter.  T
27260 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20  o be clear: the 
27270 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
27280 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74  number of <u>byt
27290 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61  es</u> in the va
272a0 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  lue, not the num
272b0 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
272c0 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  s.)^.** ^If the 
272d0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
272e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
272f0 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
27300 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
27310 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
27320 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68   then the length
27330 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69   of the string i
27340 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
27350 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74  of bytes up to t
27360 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  he first zero te
27370 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20  rminator..** If 
27380 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
27390 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
273a0 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e  bind_blob() is n
273b0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a  egative, then.**
273c0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
273d0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49   undefined..** I
273e0 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65  f a non-negative
273f0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
27400 72 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f  r is provided to
27410 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
27420 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  xt().** or sqlit
27430 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
27440 20 74 68 65 6e 20 74 68 61 74 20 70 61 72 61 6d   then that param
27450 65 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65  eter must be the
27460 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20   byte offset.** 
27470 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65  where the NUL te
27480 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f  rminator would o
27490 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68  ccur assuming th
274a0 65 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55  e string were NU
274b0 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e  L.** terminated.
274c0 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61    If any NUL cha
274d0 72 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74  racters occur at
274e0 20 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65   byte offsets le
274f0 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20  ss than .** the 
27500 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75  value of the fou
27510 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68  rth parameter th
27520 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  en the resulting
27530 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69   string value wi
27540 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d  ll.** contain em
27550 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68  bedded NULs.  Th
27560 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72  e result of expr
27570 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e  essions involvin
27580 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74  g strings.** wit
27590 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20  h embedded NULs 
275a0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
275b0 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61  .** ^The fifth a
275c0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
275d0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20  e3_bind_blob(), 
275e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
275f0 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  t(), and.** sqli
27600 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
27610 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  ) is a destructo
27620 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73  r used to dispos
27630 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
27640 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72  .** string after
27650 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69   SQLite has fini
27660 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e  shed with it.  ^
27670 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
27680 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64  s called.** to d
27690 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
276a0 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65  OB or string eve
276b0 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  n if the call to
276c0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
276d0 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  ob(),.** sqlite3
276e0 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72  _bind_text(), or
276f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
27700 78 74 31 36 28 29 20 66 61 69 6c 73 2e 20 20 0a  xt16() fails.  .
27710 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68  ** ^If the fifth
27720 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
27730 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  the special valu
27740 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43  e [SQLITE_STATIC
27750 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61  ], then SQLite a
27760 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
27770 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
27780 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d  s in static, unm
27790 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64  anaged space and
277a0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
277b0 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e  o be freed..** ^
277c0 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
277d0 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61  ument has the va
277e0 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e  lue [SQLITE_TRAN
277f0 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20  SIENT], then.** 
27800 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73  SQLite makes its
27810 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
27820 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d  y of the data im
27830 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72  mediately, befor
27840 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33  e.** the sqlite3
27850 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
27860 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  e returns..**.**
27870 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
27880 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f  nd_zeroblob() ro
27890 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c  utine binds a BL
278a0 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74  OB of length N t
278b0 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64  hat.** is filled
278c0 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e   with zeroes.  ^
278d0 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20  A zeroblob uses 
278e0 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f  a fixed amount o
278f0 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73  f memory.** (jus
27900 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20  t an integer to 
27910 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77  hold its size) w
27920 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67  hile it is being
27930 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a   processed..** Z
27940 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74  eroblobs are int
27950 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61  ended to serve a
27960 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  s placeholders f
27970 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a  or BLOBs whose.*
27980 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74  * content is lat
27990 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67  er written using
279a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
279b0 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
279c0 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72  ntal BLOB I/O] r
279d0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e  outines..** ^A n
279e0 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f  egative value fo
279f0 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72  r the zeroblob r
27a00 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f  esults in a zero
27a10 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a  -length BLOB..**
27a20 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74  .** ^If any of t
27a30 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
27a40 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  *() routines are
27a50 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
27a60 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66  ULL pointer.** f
27a70 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  or the [prepared
27a80 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77   statement] or w
27a90 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73  ith a prepared s
27aa0 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69  tatement for whi
27ab0 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  ch.** [sqlite3_s
27ac0 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20  tep()] has been 
27ad0 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65  called more rece
27ae0 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74  ntly than [sqlit
27af0 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20  e3_reset()],.** 
27b00 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69  then the call wi
27b10 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
27b20 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61  E_MISUSE].  If a
27b30 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ny sqlite3_bind_
27b40 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73  ().** routine is
27b50 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61   passed a [prepa
27b60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
27b70 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e  hat has been fin
27b80 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72  alized, the.** r
27b90 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
27ba0 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
27bb0 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  harmful..**.** ^
27bc0 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74  Bindings are not
27bd0 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20   cleared by the 
27be0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
27bf0 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55  ] routine..** ^U
27c00 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  nbound parameter
27c10 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
27c20 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  d as NULL..**.**
27c30 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
27c40 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65  nd_* routines re
27c50 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
27c60 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61   on success or a
27c70 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  n.** [error code
27c80 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f  ] if anything go
27c90 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53  es wrong..** ^[S
27ca0 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20  QLITE_RANGE] is 
27cb0 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
27cc0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64  parameter.** ind
27cd0 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
27ce0 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f  ge.  ^[SQLITE_NO
27cf0 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64  MEM] is returned
27d00 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69   if malloc() fai
27d10 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ls..**.** See al
27d20 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
27d30 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
27d40 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
27d50 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
27d60 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _name()], and [s
27d70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
27d80 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
27d90 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
27da0 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ind_blob(sqlite3
27db0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
27dc0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c  st void*, int n,
27dd0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
27de0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
27df0 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  nd_double(sqlite
27e00 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f  3_stmt*, int, do
27e10 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74  uble);.int sqlit
27e20 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69  e3_bind_int(sqli
27e30 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
27e40 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
27e50 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c  3_bind_int64(sql
27e60 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
27e70 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
27e80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
27e90 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73  d_null(sqlite3_s
27ea0 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20  tmt*, int);.int 
27eb0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
27ec0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
27ed0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72   int, const char
27ee0 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
27ef0 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
27f00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
27f10 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
27f20 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
27f30 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
27f40 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
27f50 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
27f60 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
27f70 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74  int, const sqlit
27f80 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
27f90 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
27fa0 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  oblob(sqlite3_st
27fb0 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29  mt*, int, int n)
27fc0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
27fd0 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c  F: Number Of SQL
27fe0 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a   Parameters.**.*
27ff0 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
28000 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66  can be used to f
28010 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
28020 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  f [SQL parameter
28030 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70  s].** in a [prep
28040 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
28050 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73    SQL parameters
28060 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74   are tokens of t
28070 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20  he.** form "?", 
28080 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20  "?NNN", ":AAA", 
28090 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41  "$AAA", or "@AAA
280a0 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a  " that serve as.
280b0 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  ** placeholders 
280c0 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20  for values that 
280d0 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  are [sqlite3_bin
280e0 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a  d_blob | bound].
280f0 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  ** to the parame
28100 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20  ters at a later 
28110 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  time..**.** ^(Th
28120 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61  is routine actua
28130 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20  lly returns the 
28140 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72  index of the lar
28150 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29  gest (rightmost)
28160 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46  .** parameter. F
28170 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63  or all forms exc
28180 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77  ept ?NNN, this w
28190 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74  ill correspond t
281a0 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  o the.** number 
281b0 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65  of unique parame
281c0 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65  ters.  If parame
281d0 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e  ters of the ?NNN
281e0 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a   form are used,.
281f0 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20  ** there may be 
28200 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74  gaps in the list
28210 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
28220 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
28230 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
28240 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
28250 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
28260 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a  er_name()], and.
28270 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
28280 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
28290 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
282a0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
282b0 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  er_count(sqlite3
282c0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
282d0 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
282e0 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74  f A Host Paramet
282f0 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  er.**.** ^The sq
28300 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
28310 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69  eter_name(P,N) i
28320 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
28330 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
28340 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61  the N-th [SQL pa
28350 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20  rameter] in the 
28360 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28370 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c  ent] P..** ^(SQL
28380 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
28390 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f  he form "?NNN" o
283a0 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
283b0 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
283c0 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63  have a name whic
283d0 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20  h is the string 
283e0 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
283f0 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
28400 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69  AAA".** respecti
28410 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65  vely..** In othe
28420 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69  r words, the ini
28430 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20  tial ":" or "$" 
28440 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a  or "@" or "?".**
28450 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20   is included as 
28460 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65  part of the name
28470 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65  .)^.** ^Paramete
28480 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
28490 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c  ?" without a fol
284a0 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68  lowing integer h
284b0 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61  ave no name.** a
284c0 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20  nd are referred 
284d0 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22  to as "nameless"
284e0 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70   or "anonymous p
284f0 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a  arameters"..**.*
28500 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73  * ^The first hos
28510 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  t parameter has 
28520 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e  an index of 1, n
28530 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ot 0..**.** ^If 
28540 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f  the value N is o
28550 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69  ut of range or i
28560 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d  f the N-th param
28570 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c  eter is.** namel
28580 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69  ess, then NULL i
28590 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68  s returned.  ^Th
285a0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
285b0 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69  g is.** always i
285c0 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  n UTF-8 encoding
285d0 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d   even if the nam
285e0 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73  ed parameter was
285f0 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73  .** originally s
28600 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d  pecified as UTF-
28610 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70  16 in [sqlite3_p
28620 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a  repare16()] or.*
28630 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
28640 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
28650 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
28660 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
28670 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
28680 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
28690 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
286a0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
286b0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
286c0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
286d0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
286e0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
286f0 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ter_name(sqlite3
28700 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f  _stmt*, int);../
28710 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
28720 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65  ndex Of A Parame
28730 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e  ter With A Given
28740 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74   Name.**.** ^Ret
28750 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66  urn the index of
28760 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65   an SQL paramete
28770 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  r given its name
28780 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78  .  ^The.** index
28790 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
287a0 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20  is suitable for 
287b0 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e  use as the secon
287c0 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
287d0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
287e0 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
287f0 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a  d()].  ^A zero.*
28800 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  * is returned if
28810 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72   no matching par
28820 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e  ameter is found.
28830 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72    ^The parameter
28840 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65  .** name must be
28850 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20   given in UTF-8 
28860 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67  even if the orig
28870 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a  inal statement.*
28880 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66  * was prepared f
28890 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20  rom UTF-16 text 
288a0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
288b0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
288c0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
288d0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
288e0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
288f0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
28900 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
28910 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
28920 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
28930 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
28940 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
28950 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
28960 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74  index(sqlite3_st
28970 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  mt*, const char 
28980 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *zName);../*.** 
28990 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
289a0 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20  All Bindings On 
289b0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
289c0 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74  ment.**.** ^Cont
289d0 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75  rary to the intu
289e0 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b  ition of many, [
289f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
28a00 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a   does not reset.
28a10 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
28a20 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64  bind_blob | bind
28a30 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70  ings] on a [prep
28a40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
28a50 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f  .** ^Use this ro
28a60 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61  utine to reset a
28a70 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  ll host paramete
28a80 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69  rs to NULL..*/.i
28a90 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  nt sqlite3_clear
28aa0 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
28ab0 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
28ac0 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
28ad0 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20  r Of Columns In 
28ae0 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a  A Result Set.**.
28af0 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e  ** ^Return the n
28b00 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
28b10 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
28b20 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  et returned by t
28b30 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
28b40 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69  statement]. ^Thi
28b50 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
28b60 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20  s 0 if pStmt is 
28b70 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  an SQL.** statem
28b80 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  ent that does no
28b90 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66  t return data (f
28ba0 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55  or example an [U
28bb0 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53  PDATE])..**.** S
28bc0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
28bd0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a  3_data_count()].
28be0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
28bf0 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69  olumn_count(sqli
28c00 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
28c10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
28c20 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20  F: Column Names 
28c30 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a  In A Result Set.
28c40 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
28c50 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
28c60 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74   name assigned t
28c70 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  o a particular c
28c80 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20  olumn.** in the 
28c90 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
28ca0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
28cb0 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  nt.  ^The sqlite
28cc0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a  3_column_name().
28cd0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
28ce0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
28cf0 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
28d00 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
28d10 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
28d20 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
28d30 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
28d40 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
28d50 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
28d60 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66   string.  ^The f
28d70 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
28d80 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
28d90 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68  statement].** th
28da0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
28db0 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
28dc0 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e  ment. ^The secon
28dd0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
28de0 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d  he.** column num
28df0 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d  ber.  ^The leftm
28e00 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75  ost column is nu
28e10 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54  mber 0..**.** ^T
28e20 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
28e30 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61  ng pointer is va
28e40 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72  lid until either
28e50 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
28e60 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20  tatement].** is 
28e70 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71  destroyed by [sq
28e80 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
28e90 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
28ea0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
28eb0 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
28ec0 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
28ed0 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
28ee0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
28ef0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
28f00 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
28f10 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a  he next call to.
28f20 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
28f30 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69  n_name() or sqli
28f40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
28f50 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  6() on the same 
28f60 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  column..**.** ^I
28f70 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
28f80 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20  () fails during 
28f90 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f  the processing o
28fa0 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65  f either routine
28fb0 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  .** (for example
28fc0 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72   during a conver
28fd0 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20  sion from UTF-8 
28fe0 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20  to UTF-16) then 
28ff0 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
29000 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
29010 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
29020 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  f a result colum
29030 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  n is the value o
29040 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73  f the "AS" claus
29050 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f  e for.** that co
29060 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69  lumn, if there i
29070 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20  s an AS clause. 
29080 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   If there is no 
29090 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65  AS clause.** the
290a0 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
290b0 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70  e column is unsp
290c0 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20  ecified and may 
290d0 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f  change from.** o
290e0 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ne release of SQ
290f0 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74  Lite to the next
29100 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
29110 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
29120 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
29130 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73  t*, int N);.cons
29140 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
29150 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71  column_name16(sq
29160 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
29170 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   N);../*.** CAPI
29180 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20  3REF: Source Of 
29190 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20  Data In A Query 
291a0 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  Result.**.** ^Th
291b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f  ese routines pro
291c0 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20  vide a means to 
291d0 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61  determine the da
291e0 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
291f0 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75  nd.** table colu
29200 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f  mn that is the o
29210 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69  rigin of a parti
29220 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c  cular result col
29230 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43  umn in.** [SELEC
29240 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  T] statement..**
29250 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   ^The name of th
29260 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61  e database or ta
29270 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61  ble or column ca
29280 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  n be returned as
29290 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46  .** either a UTF
292a0 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  -8 or UTF-16 str
292b0 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61  ing.  ^The _data
292c0 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  base_ routines r
292d0 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74  eturn.** the dat
292e0 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20  abase name, the 
292f0 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73  _table_ routines
29300 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c   return the tabl
29310 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74  e name, and.** t
29320 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69  he origin_ routi
29330 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63  nes return the c
29340 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e  olumn name..** ^
29350 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
29360 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ing is valid unt
29370 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  il the [prepared
29380 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64   statement] is d
29390 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e  estroyed.** usin
293a0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
293b0 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
293c0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
293d0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
293e0 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20  * reprepared by 
293f0 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74  the first call t
29400 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
29410 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  )] for a particu
29420 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e  lar run.** or un
29430 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66  til the same inf
29440 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75  ormation is requ
29450 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69  ested.** again i
29460 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e  n a different en
29470 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54  coding..**.** ^T
29480 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65  he names returne
29490 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e  d are the origin
294a0 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61  al un-aliased na
294b0 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61  mes of the.** da
294c0 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
294d0 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  nd column..**.**
294e0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
294f0 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e  ment to these in
29500 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70  terfaces is a [p
29510 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29520 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  t]..** ^These fu
29530 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69  nctions return i
29540 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
29550 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20   the Nth result 
29560 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
29570 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d  by.** the statem
29580 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ent, where N is 
29590 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74  the second funct
295a0 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
295b0 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20   ^The left-most 
295c0 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e  column is column
295d0 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75   0 for these rou
295e0 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  tines..**.** ^If
295f0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
29600 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
29610 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20  statement is an 
29620 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a  expression or.**
29630 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73   subquery and is
29640 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61   not a column va
29650 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66  lue, then all of
29660 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
29670 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e   return.** NULL.
29680 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65    ^These routine
29690 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75   might also retu
296a0 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d  rn NULL if a mem
296b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
296c0 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20  rror.** occurs. 
296d0 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65   ^Otherwise, the
296e0 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  y return the nam
296f0 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65  e of the attache
29700 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  d database, tabl
29710 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20  e,.** or column 
29720 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c  that query resul
29730 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74  t column was ext
29740 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a  racted from..**.
29750 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20  ** ^As with all 
29760 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49  other SQLite API
29770 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e  s, those whose n
29780 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31  ames end with "1
29790 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46  6" return.** UTF
297a0 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69  -16 encoded stri
297b0 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65  ngs and the othe
297c0 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  r functions retu
297d0 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  rn UTF-8..**.** 
297e0 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20  ^These APIs are 
297f0 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
29800 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61  f the library wa
29810 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
29820 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
29830 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
29840 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63  ADATA] C-preproc
29850 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a  essor symbol..**
29860 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
29870 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
29880 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74  one or more of t
29890 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67  hese routines ag
298a0 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a  ainst the same.*
298b0 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
298c0 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  ment and column 
298d0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
298e0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
298f0 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e  s are.** undefin
29900 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ed..**.** If two
29910 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
29920 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
29930 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
29940 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
29950 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61  me | column meta
29960 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d  data interfaces]
29970 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
29980 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29990 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74  ment] and result
299a0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68   column.** at th
299b0 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
299c0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
299d0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63   undefined..*/.c
299e0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
299f0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
29a00 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  se_name(sqlite3_
29a10 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
29a20 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
29a30 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
29a40 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
29a50 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
29a60 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
29a70 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
29a80 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
29a90 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
29aa0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
29ab0 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c  table_name16(sql
29ac0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
29ad0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
29ae0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
29af0 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  in_name(sqlite3_
29b00 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
29b10 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
29b20 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
29b30 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
29b40 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
29b50 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72  CAPI3REF: Declar
29b60 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41  ed Datatype Of A
29b70 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
29b80 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20  .** ^(The first 
29b90 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b  parameter is a [
29ba0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29bb0 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20  nt]..** If this 
29bc0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
29bd0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
29be0 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f  t and the Nth co
29bf0 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72  lumn of the.** r
29c00 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73  eturned result s
29c10 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45  et of that [SELE
29c20 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63  CT] is a table c
29c30 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a  olumn (not an.**
29c40 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
29c50 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68  ubquery) then th
29c60 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20  e declared type 
29c70 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20  of the table.** 
29c80 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e  column is return
29c90 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e  ed.)^  ^If the N
29ca0 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
29cb0 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61   result set is a
29cc0 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
29cd0 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65  or subquery, the
29ce0 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
29cf0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
29d00 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
29d10 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20  tring is always 
29d20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a  UTF-8 encoded..*
29d30 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70  *.** ^(For examp
29d40 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61  le, given the da
29d50 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a  tabase schema:.*
29d60 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c  *.** CREATE TABL
29d70 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29  E t1(c1 VARIANT)
29d80 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20  ;.**.** and the 
29d90 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d  following statem
29da0 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
29db0 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54  ed:.**.** SELECT
29dc0 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d   c1 + 1, c1 FROM
29dd0 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20   t1;.**.** this 
29de0 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65  routine would re
29df0 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20  turn the string 
29e00 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68  "VARIANT" for th
29e10 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a  e second result.
29e20 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29  ** column (i==1)
29e30 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69  , and a NULL poi
29e40 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72  nter for the fir
29e50 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  st result column
29e60 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a   (i==0).)^.**.**
29e70 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79   ^SQLite uses dy
29e80 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74  namic run-time t
29e90 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74  yping.  ^So just
29ea0 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d   because a colum
29eb0 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64  n.** is declared
29ec0 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61   to contain a pa
29ed0 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f  rticular type do
29ee0 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74  es not mean that
29ef0 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f   the.** data sto
29f00 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75  red in that colu
29f10 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63  mn is of the dec
29f20 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c  lared type.  SQL
29f30 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67  ite is.** strong
29f40 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68  ly typed, but th
29f50 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61  e typing is dyna
29f60 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20  mic not static. 
29f70 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73   ^Type.** is ass
29f80 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64  ociated with ind
29f90 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20  ividual values, 
29fa0 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e  not with the con
29fb0 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20  tainers.** used 
29fc0 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61  to hold those va
29fd0 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  lues..*/.const c
29fe0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
29ff0 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c  umn_decltype(sql
2a000 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2a010 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2a020 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
2a030 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73  type16(sqlite3_s
2a040 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
2a050 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c  * CAPI3REF: Eval
2a060 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74  uate An SQL Stat
2a070 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65  ement.**.** Afte
2a080 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  r a [prepared st
2a090 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65  atement] has bee
2a0a0 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  n prepared using
2a0b0 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69   either.** [sqli
2a0c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2a0d0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
2a0e0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
2a0f0 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61   one of the lega
2a100 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  cy.** interfaces
2a110 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2a120 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
2a130 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74  _prepare16()], t
2a140 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  his function.** 
2a150 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f  must be called o
2a160 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
2a170 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65   to evaluate the
2a180 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a   statement..**.*
2a190 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66  * The details of
2a1a0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
2a1b0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
2a1c0 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65  p() interface de
2a1d0 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68  pend.** on wheth
2a1e0 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  er the statement
2a1f0 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73   was prepared us
2a200 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76  ing the newer "v
2a210 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  2" interface.** 
2a220 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2a230 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
2a240 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2a250 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72  ()] or the older
2a260 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
2a270 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72  face [sqlite3_pr
2a280 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
2a290 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2a2a0 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  )].  The use of 
2a2b0 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20  the.** new "v2" 
2a2c0 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
2a2d0 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77  ommended for new
2a2e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75   applications bu
2a2f0 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  t the legacy.** 
2a300 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63  interface will c
2a310 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75  ontinue to be su
2a320 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  pported..**.** ^
2a330 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
2a340 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74  terface, the ret
2a350 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62  urn value will b
2a360 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  e either [SQLITE
2a370 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  _BUSY],.** [SQLI
2a380 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  TE_DONE], [SQLIT
2a390 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f  E_ROW], [SQLITE_
2a3a0 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49  ERROR], or [SQLI
2a3b0 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e  TE_MISUSE]..** ^
2a3c0 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  With the "v2" in
2a3d0 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20  terface, any of 
2a3e0 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c  the other [resul
2a3f0 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b  t codes] or.** [
2a400 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
2a410 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20  codes] might be 
2a420 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c  returned as well
2a430 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
2a440 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61  _BUSY] means tha
2a450 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  t the database e
2a460 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65  ngine was unable
2a470 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a   to acquire the.
2a480 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b  ** database lock
2a490 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f  s it needs to do
2a4a0 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74   its job.  ^If t
2a4b0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2a4c0 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72  a [COMMIT].** or
2a4d0 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20   occurs outside 
2a4e0 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  of an explicit t
2a4f0 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
2a500 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74   you can retry t
2a510 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e  he.** statement.
2a520 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
2a530 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d  nt is not a [COM
2a540 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20  MIT] and occurs 
2a550 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70  within an.** exp
2a560 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
2a570 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c  n then you shoul
2a580 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74  d rollback the t
2a590 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72  ransaction befor
2a5a0 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e  e.** continuing.
2a5b0 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
2a5c0 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  DONE] means that
2a5d0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
2a5e0 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
2a5f0 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73  uting.** success
2a600 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f  fully.  sqlite3_
2a610 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
2a620 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
2a630 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61  n on this virtua
2a640 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74  l.** machine wit
2a650 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69  hout first calli
2a660 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
2a670 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  t()] to reset th
2a680 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  e virtual.** mac
2a690 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73  hine back to its
2a6a0 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a   initial state..
2a6b0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51  **.** ^If the SQ
2a6c0 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e  L statement bein
2a6d0 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72  g executed retur
2a6e0 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65  ns any data, the
2a6f0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a  n [SQLITE_ROW].*
2a700 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61  * is returned ea
2a710 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f  ch time a new ro
2a720 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61  w of data is rea
2a730 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e  dy for processin
2a740 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  g by the.** call
2a750 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d  er. The values m
2a760 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75  ay be accessed u
2a770 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e  sing the [column
2a780 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
2a790 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  s]..** sqlite3_s
2a7a0 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20  tep() is called 
2a7b0 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76  again to retriev
2a7c0 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f  e the next row o
2a7d0 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  f data..**.** ^[
2a7e0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65  SQLITE_ERROR] me
2a7f0 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74  ans that a run-t
2a800 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20  ime error (such 
2a810 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a  as a constraint.
2a820 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61  ** violation) ha
2a830 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c  s occurred.  sql
2a840 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
2a850 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
2a860 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65   again on.** the
2a870 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d   VM. More inform
2a880 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75  ation may be fou
2a890 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  nd by calling [s
2a8a0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
2a8b0 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c  ..** ^With the l
2a8c0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
2a8d0 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63   a more specific
2a8e0 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72   error code (for
2a8f0 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51   example,.** [SQ
2a900 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c  LITE_INTERRUPT],
2a910 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
2a920 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  , [SQLITE_CORRUP
2a930 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68  T], and so forth
2a940 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61  ).** can be obta
2a950 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ined by calling 
2a960 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2a970 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ] on the.** [pre
2a980 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a990 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  .  ^In the "v2" 
2a9a0 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68  interface,.** th
2a9b0 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
2a9c0 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
2a9d0 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20  turned directly 
2a9e0 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
2a9f0 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  )..**.** [SQLITE
2aa00 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74  _MISUSE] means t
2aa10 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75  hat the this rou
2aa20 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20  tine was called 
2aa30 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e  inappropriately.
2aa40 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77  .** Perhaps it w
2aa50 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  as called on a [
2aa60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2aa70 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  nt] that has.** 
2aa80 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71  already been [sq
2aa90 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
2aaa0 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f   finalized] or o
2aab0 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a  n one that had.*
2aac0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  * previously ret
2aad0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52  urned [SQLITE_ER
2aae0 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROR] or [SQLITE_
2aaf0 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f  DONE].  Or it co
2ab00 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61  uld.** be the ca
2ab10 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65  se that the same
2ab20 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2ab30 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73  tion is being us
2ab40 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20  ed by two or.** 
2ab50 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20  more threads at 
2ab60 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20  the same moment 
2ab70 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46  in time..**.** F
2ab80 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20  or all versions 
2ab90 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20  of SQLite up to 
2aba0 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e  and including 3.
2abb0 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74  6.23.1, a call t
2abc0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  o.** [sqlite3_re
2abd0 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69  set()] was requi
2abe0 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  red after sqlite
2abf0 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65  3_step() returne
2ac00 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74  d anything.** ot
2ac10 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
2ac20 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79  _ROW] before any
2ac30 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
2ac40 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c  cation of.** sql
2ac50 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61  ite3_step().  Fa
2ac60 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74  ilure to reset t
2ac70 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
2ac80 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20  ement using .** 
2ac90 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2aca0 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  ] would result i
2acb0 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  n an [SQLITE_MIS
2acc0 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d  USE] return from
2acd0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
2ace0 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 76  ().  But after v
2acf0 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c  ersion 3.6.23.1,
2ad00 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2ad10 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67  began.** calling
2ad20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2ad30 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  )] automatically
2ad40 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73   in this circums
2ad50 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20  tance rather.** 
2ad60 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b  than returning [
2ad70 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
2ad80 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e   This is not con
2ad90 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74  sidered a compat
2ada0 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b  ibility.** break
2adb0 20 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70   because any app
2adc0 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76  lication that ev
2add0 65 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53  er receives an S
2ade0 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72  QLITE_MISUSE err
2adf0 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20  or.** is broken 
2ae00 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20  by definition.  
2ae10 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  The [SQLITE_OMIT
2ae20 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70  _AUTORESET] comp
2ae30 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a  ile-time option.
2ae40 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ** can be used t
2ae50 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65  o restore the le
2ae60 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a  gacy behavior..*
2ae70 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e  *.** <b>Goofy In
2ae80 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f  terface Alert:</
2ae90 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79  b> In the legacy
2aea0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20   interface, the 
2aeb0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a  sqlite3_step().*
2aec0 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74  * API always ret
2aed0 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65  urns a generic e
2aee0 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49  rror code, [SQLI
2aef0 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f  TE_ERROR], follo
2af00 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f  wing any.** erro
2af10 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  r other than [SQ
2af20 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b  LITE_BUSY] and [
2af30 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
2af40 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a   You must call.*
2af50 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2af60 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2af70 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f  finalize()] in o
2af80 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65  rder to find one
2af90 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69   of the.** speci
2afa0 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
2afb0 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65  ] that better de
2afc0 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
2afd0 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74  r..** We admit t
2afe0 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f  hat this is a go
2aff0 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65  ofy design.  The
2b000 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65   problem has bee
2b010 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20  n fixed.** with 
2b020 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2b030 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70  ce.  If you prep
2b040 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20  are all of your 
2b050 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
2b060 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  * using either [
2b070 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2b080 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
2b090 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2b0a0 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  ] instead.** of 
2b0b0 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69  the legacy [sqli
2b0c0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
2b0d0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
2b0e0 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61  are16()] interfa
2b0f0 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ces,.** then the
2b100 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b   more specific [
2b110 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65  error codes] are
2b120 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
2b130 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ly.** by sqlite3
2b140 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73  _step().  The us
2b150 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e  e of the "v2" in
2b160 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
2b170 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  mended..*/.int s
2b180 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69  qlite3_step(sqli
2b190 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2b1a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
2b1b0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2b1c0 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a  n a result set.*
2b1d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2b1e0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
2b1f0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2b200 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2b210 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a  columns in the.*
2b220 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  * current row of
2b230 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2b240 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
2b250 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49  tement] P..** ^I
2b260 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  f prepared state
2b270 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20  ment P does not 
2b280 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61  have results rea
2b290 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  dy to return.** 
2b2a0 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68  (via calls to th
2b2b0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
2b2c0 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  n_int | sqlite3_
2b2d0 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a  column_*()] of.*
2b2e0 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68  * interfaces) th
2b2f0 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  en sqlite3_data_
2b300 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73  count(P) returns
2b310 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69   0..** ^The sqli
2b320 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2b330 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72  ) routine also r
2b340 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73  eturns 0 if P is
2b350 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
2b360 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2b370 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
2b380 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
2b390 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   if the previous
2b3a0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
2b3b0 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65  ite3_step](P) re
2b3c0 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44  turned [SQLITE_D
2b3d0 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  ONE].  ^The sqli
2b3e0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2b3f0 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e  ).** will return
2b400 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65   non-zero if pre
2b410 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73  vious call to [s
2b420 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20  qlite3_step](P) 
2b430 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c  returned.** [SQL
2b440 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74  ITE_ROW], except
2b450 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20   in the case of 
2b460 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72  the [PRAGMA incr
2b470 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a  emental_vacuum].
2b480 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61  ** where it alwa
2b490 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20  ys returns zero 
2b4a0 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20  since each step 
2b4b0 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74  of that multi-st
2b4c0 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74  ep.** pragma ret
2b4d0 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f  urns 0 columns o
2b4e0 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65  f data..**.** Se
2b4f0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2b500 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
2b510 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2b520 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74  data_count(sqlit
2b530 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2b540 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b550 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61  : Fundamental Da
2b560 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f  tatypes.** KEYWO
2b570 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54  RDS: SQLITE_TEXT
2b580 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76  .**.** ^(Every v
2b590 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68  alue in SQLite h
2b5a0 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66  as one of five f
2b5b0 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74  undamental datat
2b5c0 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ypes:.**.** <ul>
2b5d0 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
2b5e0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
2b5f0 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45  * <li> 64-bit IE
2b600 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  EE floating poin
2b610 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e  t number.** <li>
2b620 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20   string.** <li> 
2b630 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c  BLOB.** <li> NUL
2b640 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  L.** </ul>)^.**.
2b650 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
2b660 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72  ts are codes for
2b670 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74   each of those t
2b680 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  ypes..**.** Note
2b690 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45   that the SQLITE
2b6a0 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77  _TEXT constant w
2b6b0 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20  as also used in 
2b6c0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
2b6d0 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65  .** for a comple
2b6e0 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d  tely different m
2b6f0 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72  eaning.  Softwar
2b700 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61  e that links aga
2b710 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c  inst both.** SQL
2b720 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e  ite version 2 an
2b730 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  d SQLite version
2b740 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51   3 should use SQ
2b750 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a  LITE3_TEXT, not.
2b760 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a  ** SQLITE_TEXT..
2b770 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2b780 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65  E_INTEGER  1.#de
2b790 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41  fine SQLITE_FLOA
2b7a0 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  T    2.#define S
2b7b0 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34  QLITE_BLOB     4
2b7c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2b7d0 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65  NULL     5.#ifde
2b7e0 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20  f SQLITE_TEXT.# 
2b7f0 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  undef SQLITE_TEX
2b800 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  T.#else.# define
2b810 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20   SQLITE_TEXT    
2b820 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e   3.#endif.#defin
2b830 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20  e SQLITE3_TEXT  
2b840 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     3../*.** CAPI
2b850 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c  3REF: Result Val
2b860 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79  ues From A Query
2b870 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
2b880 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
2b890 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  ctions}.**.** Th
2b8a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ese routines for
2b8b0 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65  m the "result se
2b8c0 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  t" interface..**
2b8d0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
2b8e0 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  nes return infor
2b8f0 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73  mation about a s
2b900 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20  ingle column of 
2b910 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72  the current.** r
2b920 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71  esult row of a q
2b930 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79  uery.  ^In every
2b940 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20   case the first 
2b950 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
2b960 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
2b970 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b980 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69  ent] that is bei
2b990 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68  ng evaluated (th
2b9a0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  e [sqlite3_stmt*
2b9b0 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65  ].** that was re
2b9c0 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
2b9d0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2b9e0 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73  )] or one of its
2b9f0 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e   variants).** an
2ba00 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  d the second arg
2ba10 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
2ba20 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
2ba30 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72   for which infor
2ba40 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  mation.** should
2ba50 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54   be returned. ^T
2ba60 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
2ba70 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
2ba80 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64   set has the ind
2ba90 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75  ex 0..** ^The nu
2baa0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2bab0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61  in the result ca
2bac0 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
2bad0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
2bae0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
2baf0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  ]..**.** If the 
2bb00 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
2bb10 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  es not currently
2bb20 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69   point to a vali
2bb30 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65  d row, or if the
2bb40 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78  .** column index
2bb50 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
2bb60 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  , the result is 
2bb70 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
2bb80 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
2bb90 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
2bba0 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  when the most re
2bbb0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  cent call to.** 
2bbc0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2bbd0 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53   has returned [S
2bbe0 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e  QLITE_ROW] and n
2bbf0 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
2bc00 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20  e3_reset()] nor 
2bc10 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2bc20 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63  e()] have been c
2bc30 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74  alled subsequent
2bc40 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66  ly..** If any of
2bc50 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2bc60 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72  are called after
2bc70 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2bc80 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
2bc90 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
2bca0 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
2bcb0 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
2bcc0 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e  rned.** somethin
2bcd0 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
2bce0 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72  LITE_ROW], the r
2bcf0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
2bd00 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c  ined..** If [sql
2bd10 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
2bd20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2bd30 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
2bd40 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65  nalize()].** are
2bd50 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64   called from a d
2bd60 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
2bd70 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65  while any of the
2bd80 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
2bd90 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e  re pending, then
2bda0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2bdb0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2bdc0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
2bdd0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75  olumn_type() rou
2bde0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
2bdf0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
2be00 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63  GER | datatype c
2be10 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69  ode] for the ini
2be20 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a  tial data type.*
2be30 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  * of the result 
2be40 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65  column.  ^The re
2be50 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20  turned value is 
2be60 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
2be70 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  NTEGER],.** [SQL
2be80 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c  ITE_FLOAT], [SQL
2be90 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49  ITE_TEXT], [SQLI
2bea0 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51  TE_BLOB], or [SQ
2beb0 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65  LITE_NULL].  The
2bec0 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
2bed0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2bee0 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f  lumn_type() is o
2bef0 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69  nly meaningful i
2bf00 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e  f no type.** con
2bf10 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63  versions have oc
2bf20 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69  curred as descri
2bf30 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65  bed below.  Afte
2bf40 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  r a type convers
2bf50 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75  ion,.** the valu
2bf60 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
2bf70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2bf80 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
2bf90 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72  .  Future.** ver
2bfa0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
2bfb0 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62  may change the b
2bfc0 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74  ehavior of sqlit
2bfd0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2bfe0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
2bff0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  type conversion.
2c000 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
2c010 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
2c020 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  or UTF-8 string 
2c030 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
2c040 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a  _column_bytes().
2c050 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
2c060 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2c070 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
2c080 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
2c090 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2c0a0 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72   is a UTF-16 str
2c0b0 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
2c0c0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2c0d0 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
2c0e0 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38   string to UTF-8
2c0f0 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
2c100 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2c110 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
2c120 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
2c130 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
2c140 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c150 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20  bytes() uses.** 
2c160 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
2c170 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
2c180 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
2c190 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64  UTF-8 string and
2c1a0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
2c1b0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2c1c0 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
2c1d0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2c1e0 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
2c1f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2c200 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a  ytes() returns z
2c210 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ero..**.** ^If t
2c220 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
2c230 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74  LOB or UTF-16 st
2c240 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
2c250 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2c260 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  es16().** routin
2c270 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
2c280 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2c290 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
2c2a0 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
2c2b0 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
2c2c0 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  -8 string, then 
2c2d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2c2e0 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74  ytes16() convert
2c2f0 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
2c300 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68  to UTF-16 and th
2c310 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
2c320 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
2c330 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2c340 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
2c350 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
2c360 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2c370 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
2c380 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
2c390 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
2c3a0 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31  value to a UTF-1
2c3b0 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  6 string and ret
2c3c0 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
2c3d0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2c3e0 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
2c3f0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2c400 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69   NULL, then sqli
2c410 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2c420 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72  16() returns zer
2c430 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61  o..**.** ^The va
2c440 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
2c450 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2c460 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a  _bytes()] and .*
2c470 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2c480 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20  n_bytes16()] do 
2c490 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20  not include the 
2c4a0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73  zero terminators
2c4b0 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f   at the end.** o
2c4c0 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e  f the string.  ^
2c4d0 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65  For clarity: the
2c4e0 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
2c4f0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
2c500 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
2c510 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
2c520 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61  umn_bytes16()] a
2c530 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  re the number of
2c540 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65  .** bytes in the
2c550 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65   string, not the
2c560 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
2c570 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74  cters..**.** ^St
2c580 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
2c590 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2c5a0 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69  _text() and sqli
2c5b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2c5c0 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70  6(),.** even emp
2c5d0 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20  ty strings, are 
2c5e0 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
2c5f0 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65  inated.  ^The re
2c600 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72  turn.** value fr
2c610 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  om sqlite3_colum
2c620 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a  n_blob() for a z
2c630 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20  ero-length BLOB 
2c640 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2c650 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62  r..**.** ^The ob
2c660 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
2c670 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2c680 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a  _value()] is an.
2c690 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
2c6a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2c6b0 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f  bject.  An unpro
2c6c0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2c6d0 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d  alue object.** m
2c6e0 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
2c6f0 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69  with [sqlite3_bi
2c700 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  nd_value()] and 
2c710 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2c720 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20  value()]..** If 
2c730 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  the [unprotected
2c740 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2c750 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
2c760 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
2c770 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
2c780 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74  s used in any ot
2c790 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69  her way, includi
2c7a0 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72  ng calls.** to r
2c7b0 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
2c7c0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
2c7d0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
2c7e0 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
2c7f0 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
2c800 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20  _bytes()], then 
2c810 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
2c820 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2c830 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2c840 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65  attempt to conve
2c850 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65  rt the value whe
2c860 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20  re appropriate. 
2c870 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65   ^For.** example
2c880 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61  , if the interna
2c890 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
2c8a0 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20   is FLOAT and a 
2c8b0 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69  text result.** i
2c8c0 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71  s requested, [sq
2c8d0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
2c8e0 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  ] is used intern
2c8f0 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20  ally to perform 
2c900 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  the.** conversio
2c910 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  n automatically.
2c920 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e    ^(The followin
2c930 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20  g table details 
2c940 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a  the conversions.
2c950 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c  ** that are appl
2c960 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ied:.**.** <bloc
2c970 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c  kquote>.** <tabl
2c980 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a  e border="1">.**
2c990 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e   <tr><th> Intern
2c9a0 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  al<br>Type <th> 
2c9b0 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70  Requested<br>Typ
2c9c0 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69  e <th>  Conversi
2c9d0 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64  on.**.** <tr><td
2c9e0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
2c9f0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52  INTEGER   <td> R
2ca00 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74  esult is 0.** <t
2ca10 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2ca20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
2ca30 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e  td> Result is 0.
2ca40 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
2ca50 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45  ULL    <td>   TE
2ca60 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  XT    <td> Resul
2ca70 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  t is NULL pointe
2ca80 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  r.** <tr><td>  N
2ca90 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  ULL    <td>   BL
2caa0 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  OB    <td> Resul
2cab0 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  t is NULL pointe
2cac0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
2cad0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f  TEGER  <td>  FLO
2cae0 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
2caf0 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20  rt from integer 
2cb00 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  to float.** <tr>
2cb10 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
2cb20 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
2cb30 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
2cb40 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72  g of the integer
2cb50 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
2cb60 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f  EGER  <td>   BLO
2cb70 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
2cb80 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a  s INTEGER->TEXT.
2cb90 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
2cba0 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  AT   <td> INTEGE
2cbb0 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74  R   <td> Convert
2cbc0 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69   from float to i
2cbd0 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
2cbe0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
2cbf0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2cc00 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
2cc10 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20  of the float.** 
2cc20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
2cc30 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2cc40 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c   <td> Same as FL
2cc50 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  OAT->TEXT.** <tr
2cc60 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
2cc70 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
2cc80 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a  d> Use atoi().**
2cc90 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
2cca0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
2ccb0 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28    <td> Use atof(
2ccc0 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  ).** <tr><td>  T
2ccd0 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  EXT    <td>   BL
2cce0 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68  OB    <td> No ch
2ccf0 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ange.** <tr><td>
2cd00 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49    BLOB    <td> I
2cd10 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
2cd20 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68  nvert to TEXT th
2cd30 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a  en use atoi().**
2cd40 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
2cd50 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
2cd60 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74    <td> Convert t
2cd70 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20  o TEXT then use 
2cd80 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
2cd90 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
2cda0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2cdb0 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69  Add a zero termi
2cdc0 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a  nator if needed.
2cdd0 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c  ** </table>.** <
2cde0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
2cdf0 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61  *.** The table a
2ce00 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72  bove makes refer
2ce10 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64  ence to standard
2ce20 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74   C library funct
2ce30 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61  ions atoi().** a
2ce40 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69  nd atof().  SQLi
2ce50 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c  te does not real
2ce60 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e  ly use these fun
2ce70 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20  ctions.  It has 
2ce80 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76  its.** own equiv
2ce90 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72  alent internal r
2cea0 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74  outines.  The at
2ceb0 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20  oi() and atof() 
2cec0 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65  names are.** use
2ced0 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66  d in the table f
2cee0 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62  or brevity and b
2cef0 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20  ecause they are 
2cf00 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74  familiar to most
2cf10 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72  .** C programmer
2cf20 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
2cf30 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e  at when type con
2cf40 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20  versions occur, 
2cf50 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
2cf60 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61  d by prior.** ca
2cf70 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2cf80 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71  olumn_blob(), sq
2cf90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2cfa0 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73  t(), and/or.** s
2cfb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2cfc0 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e  xt16() may be in
2cfd0 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79  validated..** Ty
2cfe0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61  pe conversions a
2cff0 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c  nd pointer inval
2d000 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f  idations might o
2d010 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ccur.** in the f
2d020 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a  ollowing cases:.
2d030 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
2d040 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
2d050 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42  ontent is a BLOB
2d060 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2d070 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a  umn_text() or.**
2d080 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
2d090 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
2d0a0 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f   called.  A zero
2d0b0 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68  -terminator migh
2d0c0 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74  t.**      need t
2d0d0 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68  o be added to th
2d0e0 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a  e string.</li>.*
2d0f0 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
2d100 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
2d110 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c  F-8 text and sql
2d120 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2d130 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  s16() or.**     
2d140 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d150 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
2d160 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
2d170 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
2d180 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
2d190 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  F-16.</li>.** <l
2d1a0 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
2d1b0 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36  ontent is UTF-16
2d1c0 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
2d1d0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2d1e0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
2d1f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2d200 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
2d210 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
2d220 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
2d230 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c      to UTF-8.</l
2d240 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
2d250 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62  * ^Conversions b
2d260 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20  etween UTF-16be 
2d270 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65  and UTF-16le are
2d280 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20   always done in 
2d290 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20  place and do.** 
2d2a0 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61  not invalidate a
2d2b0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20   prior pointer, 
2d2c0 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65  though of course
2d2d0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
2d2e0 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  the buffer.** th
2d2f0 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69  at the prior poi
2d300 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20  nter references 
2d310 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d  will have been m
2d320 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20  odified.  Other 
2d330 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76  kinds.** of conv
2d340 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20  ersion are done 
2d350 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74  in place when it
2d360 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75   is possible, bu
2d370 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79  t sometimes they
2d380 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73  .** are not poss
2d390 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73  ible and in thos
2d3a0 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f  e cases prior po
2d3b0 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c  inters are inval
2d3c0 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  idated..**.** Th
2d3d0 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73  e safest and eas
2d3e0 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72  iest to remember
2d3f0 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e   policy is to in
2d400 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69  voke these routi
2d410 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66  nes.** in one of
2d420 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77   the following w
2d430 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ays:.**.** <ul>.
2d440 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
2d450 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f  column_text() fo
2d460 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
2d470 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2d480 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
2d490 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2d4a0 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  b() followed by 
2d4b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2d4c0 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
2d4d0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
2d4e0 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c  mn_text16() foll
2d4f0 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
2d500 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2d510 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
2d520 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  *.** In other wo
2d530 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20  rds, you should 
2d540 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  call sqlite3_col
2d550 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73  umn_text(),.** s
2d560 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2d570 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  ob(), or sqlite3
2d580 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2d590 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20   first to force 
2d5a0 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  the result.** in
2d5b0 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66  to the desired f
2d5c0 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f  ormat, then invo
2d5d0 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ke sqlite3_colum
2d5e0 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
2d5f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2d600 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64  ytes16() to find
2d610 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
2d620 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74   result.  Do not
2d630 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f   mix calls.** to
2d640 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d650 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
2d660 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
2d670 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  with calls to.**
2d680 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d690 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64  bytes16(), and d
2d6a0 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20  o not mix calls 
2d6b0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
2d6c0 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69  n_text16().** wi
2d6d0 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  th calls to sqli
2d6e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2d6f0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ()..**.** ^The p
2d700 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
2d710 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
2d720 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
2d730 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20  on occurs as.** 
2d740 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c  described above,
2d750 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
2d760 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
2d770 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2d780 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
2d790 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
2d7a0 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f  lled.  ^The memo
2d7b0 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f  ry space used to
2d7c0 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a   hold strings.**
2d7d0 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72   and BLOBs is fr
2d7e0 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  eed automaticall
2d7f0 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62  y.  Do <b>not</b
2d800 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74  > pass the point
2d810 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ers returned.** 
2d820 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2d830 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
2d840 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
2d850 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b  , etc. into.** [
2d860 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
2d870 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65  .**.** ^(If a me
2d880 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2d890 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
2d8a0 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69  ing the evaluati
2d8b0 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  on of any.** of 
2d8c0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20  these routines, 
2d8d0 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  a default value 
2d8e0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
2d8f0 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a  e default value.
2d900 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65  ** is either the
2d910 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20   integer 0, the 
2d920 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
2d930 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20  umber 0.0, or a 
2d940 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e  NULL.** pointer.
2d950 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c    Subsequent cal
2d960 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
2d970 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72  rrcode()] will r
2d980 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
2d990 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f  _NOMEM].)^.*/.co
2d9a0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2d9b0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71  3_column_blob(sq
2d9c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2d9d0 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
2d9e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2d9f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2da00 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
2da10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2da20 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74  tes16(sqlite3_st
2da30 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2da40 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63  double sqlite3_c
2da50 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c  olumn_double(sql
2da60 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2da70 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
2da80 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71  e3_column_int(sq
2da90 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2daa0 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
2dab0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f  int64 sqlite3_co
2dac0 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74  lumn_int64(sqlit
2dad0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2dae0 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67  ol);.const unsig
2daf0 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
2db00 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71  3_column_text(sq
2db10 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2db20 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f   iCol);.const vo
2db30 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2db40 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  mn_text16(sqlite
2db50 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2db60 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
2db70 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69  column_type(sqli
2db80 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2db90 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61  Col);.sqlite3_va
2dba0 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  lue *sqlite3_col
2dbb0 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  umn_value(sqlite
2dbc0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2dbd0 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
2dbe0 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50  REF: Destroy A P
2dbf0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2dc00 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e  t Object.**.** ^
2dc10 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
2dc20 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  lize() function 
2dc30 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c  is called to del
2dc40 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ete a [prepared 
2dc50 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
2dc60 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
2dc70 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
2dc80 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65   the statement e
2dc90 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72  ncountered no er
2dca0 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68  rors.** or if th
2dcb0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
2dcc0 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61  ever been evalua
2dcd0 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ted, then sqlite
2dce0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74  3_finalize() ret
2dcf0 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  urns.** SQLITE_O
2dd00 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  K.  ^If the most
2dd10 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69   recent evaluati
2dd20 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20  on of statement 
2dd30 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a  S failed, then.*
2dd40 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  * sqlite3_finali
2dd50 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68  ze(S) returns th
2dd60 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  e appropriate [e
2dd70 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  rror code] or.**
2dd80 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
2dd90 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
2dda0 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
2ddb0 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63  ize(S) routine c
2ddc0 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20  an be called at 
2ddd0 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67  any point during
2dde0 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63  .** the life cyc
2ddf0 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  le of [prepared 
2de00 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a  statement] S:.**
2de10 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e   before statemen
2de20 74 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c  t S is ever eval
2de30 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20  uated, after.** 
2de40 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c  one or more call
2de50 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
2de60 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72  set()], or after
2de70 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20   any call.** to 
2de80 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2de90 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
2dea0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
2deb0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a  e statement has.
2dec0 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65  ** completed exe
2ded0 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  cution..**.** ^I
2dee0 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
2def0 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20  finalize() on a 
2df00 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
2df10 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
2df20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
2df30 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e  ication must fin
2df40 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65  alize every [pre
2df50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2df60 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f   in order to avo
2df70 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c  id.** resource l
2df80 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67  eaks.  It is a g
2df90 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f  rievous error fo
2dfa0 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
2dfb0 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a  n to try to use.
2dfc0 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74  ** a prepared st
2dfd0 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
2dfe0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
2dff0 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66  zed.  Any use of
2e000 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73   a prepared.** s
2e010 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69  tatement after i
2e020 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
2e030 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20  ized can result 
2e040 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  in undefined and
2e050 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20  .** undesirable 
2e060 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73  behavior such as
2e070 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68   segfaults and h
2e080 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a  eap corruption..
2e090 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66  */.int sqlite3_f
2e0a0 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f  inalize(sqlite3_
2e0b0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2e0c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2e0d0 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20  eset A Prepared 
2e0e0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
2e0f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2e100 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74  e3_reset() funct
2e110 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
2e120 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72   reset a [prepar
2e130 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
2e140 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20   object back to 
2e150 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
2e160 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72  e, ready to be r
2e170 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e  e-executed..** ^
2e180 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  Any SQL statemen
2e190 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74  t variables that
2e1a0 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e   had values boun
2e1b0 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a  d to them using.
2e1c0 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
2e1d0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  bind_blob | sqli
2e1e0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49  te3_bind_*() API
2e1f0 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76  ] retain their v
2e200 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73  alues..** Use [s
2e210 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
2e220 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65  dings()] to rese
2e230 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a  t the bindings..
2e240 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
2e250 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
2e260 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74  terface resets t
2e270 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2e280 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63  tement] S.** bac
2e290 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  k to the beginni
2e2a0 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61  ng of its progra
2e2b0 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  m..**.** ^If the
2e2c0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
2e2d0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
2e2e0 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
2e2f0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2e300 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65  ement] S returne
2e310 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f  d [SQLITE_ROW] o
2e320 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  r [SQLITE_DONE],
2e330 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74  .** or if [sqlit
2e340 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20  e3_step(S)] has 
2e350 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65  never before bee
2e360 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a  n called on S,.*
2e370 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  * then [sqlite3_
2e380 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
2e390 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
2e3a0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
2e3b0 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
2e3c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2e3d0 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
2e3e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2e3f0 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61  t] S indicated a
2e400 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a  n error, then.**
2e410 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2e420 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61  S)] returns an a
2e430 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
2e440 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  r code]..**.** ^
2e450 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
2e460 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
2e470 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
2e480 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f   the values.** o
2e490 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62  f any [sqlite3_b
2e4a0 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67  ind_blob|binding
2e4b0 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61  s] on the [prepa
2e4c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2e4d0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2e4e0 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73  _reset(sqlite3_s
2e4f0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2e500 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72  .** CAPI3REF: Cr
2e510 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65  eate Or Redefine
2e520 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   SQL Functions.*
2e530 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e  * KEYWORDS: {fun
2e540 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
2e550 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57  outines}.** KEYW
2e560 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
2e570 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2e580 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57  unction}.** KEYW
2e590 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
2e5a0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2e5b0 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  unctions}.**.** 
2e5c0 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
2e5d0 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b   (collectively k
2e5e0 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f  nown as "functio
2e5f0 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
2e600 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65  nes").** are use
2e610 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e  d to add SQL fun
2e620 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
2e630 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66  ates or to redef
2e640 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  ine the behavior
2e650 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20  .** of existing 
2e660 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
2e670 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68   aggregates.  Th
2e680 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63  e only differenc
2e690 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  es between.** th
2e6a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
2e6b0 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69   the text encodi
2e6c0 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a  ng expected for.
2e6d0 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  ** the second pa
2e6e0 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d  rameter (the nam
2e6f0 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  e of the functio
2e700 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29  n being created)
2e710 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73  .** and the pres
2e720 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20  ence or absence 
2e730 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  of a destructor 
2e740 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20  callback for.** 
2e750 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2e760 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  data pointer..**
2e770 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70  .** ^The first p
2e780 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2e790 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2e7a0 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74  tion] to which t
2e7b0 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69  he SQL.** functi
2e7c0 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65  on is to be adde
2e7d0 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69  d.  ^If an appli
2e7e0 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65  cation uses more
2e7f0 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61   than one databa
2e800 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
2e810 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f   then applicatio
2e820 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2e830 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20  nctions must be 
2e840 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68  added.** to each
2e850 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2e860 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e  tion separately.
2e870 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
2e880 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
2e890 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2e8a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
2e8b0 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a  be created or.**
2e8c0 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   redefined.  ^Th
2e8d0 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
2e8e0 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20  name is limited 
2e8f0 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20  to 255 bytes in 
2e900 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65  a UTF-8.** repre
2e910 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75  sentation, exclu
2e920 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f  sive of the zero
2e930 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e  -terminator.  ^N
2e940 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d  ote that the nam
2e950 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69  e.** length limi
2e960 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79  t is in UTF-8 by
2e970 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74  tes, not charact
2e980 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62  ers nor UTF-16 b
2e990 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20  ytes.  .** ^Any 
2e9a0 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74  attempt to creat
2e9b0 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  e a function wit
2e9c0 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a  h a longer name.
2e9d0 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69  ** will result i
2e9e0 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
2e9f0 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64  ] being returned
2ea00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
2ea10 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41  rd parameter (nA
2ea20 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75  rg).** is the nu
2ea30 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
2ea40 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66  s that the SQL f
2ea50 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
2ea60 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e  gregate takes. ^
2ea70 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  If this paramete
2ea80 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68  r is -1, then th
2ea90 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
2eaa0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d  r.** aggregate m
2eab0 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62  ay take any numb
2eac0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
2ead0 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
2eae0 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62  e limit.** set b
2eaf0 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  y [sqlite3_limit
2eb00 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ]([SQLITE_LIMIT_
2eb10 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20  FUNCTION_ARG]). 
2eb20 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   If the third.**
2eb30 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65   parameter is le
2eb40 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72  ss than -1 or gr
2eb50 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74  eater than 127 t
2eb60 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
2eb70 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64   is.** undefined
2eb80 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
2eb90 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65  rth parameter, e
2eba0 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69  TextRep, specifi
2ebb0 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49  es what.** [SQLI
2ebc0 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65  TE_UTF8 | text e
2ebd0 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51  ncoding] this SQ
2ebe0 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65  L function prefe
2ebf0 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61  rs for.** its pa
2ec00 72 61 6d 65 74 65 72 73 2e 20 20 45 76 65 72 79  rameters.  Every
2ec10 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
2ec20 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73  plementation mus
2ec30 74 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72  t be able to wor
2ec40 6b 0a 2a 2a 20 77 69 74 68 20 55 54 46 2d 38 2c  k.** with UTF-8,
2ec50 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54   UTF-16le, or UT
2ec60 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d  F-16be.  But som
2ec70 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2ec80 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65  s may be.** more
2ec90 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20   efficient with 
2eca0 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61  one encoding tha
2ecb0 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20  n another.  ^An 
2ecc0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a  application may.
2ecd0 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
2ece0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2ecf0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  n() or sqlite3_c
2ed00 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2ed10 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74  () multiple.** t
2ed20 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61  imes with the sa
2ed30 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20  me function but 
2ed40 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76  with different v
2ed50 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65  alues of eTextRe
2ed60 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74  p..** ^When mult
2ed70 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
2ed80 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
2ed90 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76   function are av
2eda0 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a  ailable, SQLite.
2edb0 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65  ** will pick the
2edc0 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76   one that involv
2edd0 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
2ede0 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76  unt of data conv
2edf0 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  ersion..** If th
2ee00 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69  ere is only a si
2ee10 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ngle implementat
2ee20 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e  ion which does n
2ee30 6f 74 20 63 61 72 65 20 77 68 61 74 20 74 65 78  ot care what tex
2ee40 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73  t.** encoding is
2ee50 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20   used, then the 
2ee60 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
2ee70 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54  should be [SQLIT
2ee80 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  E_ANY]..**.** ^(
2ee90 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  The fifth parame
2eea0 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72  ter is an arbitr
2eeb0 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ary pointer.  Th
2eec0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2eed0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74   of the.** funct
2eee0 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63  ion can gain acc
2eef0 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e  ess to this poin
2ef00 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ter using [sqlit
2ef10 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e  e3_user_data()].
2ef20 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69  )^.**.** ^The si
2ef30 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64  xth, seventh and
2ef40 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65   eighth paramete
2ef50 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70  rs, xFunc, xStep
2ef60 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65   and xFinal, are
2ef70 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
2ef80 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74  C-language funct
2ef90 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  ions that implem
2efa0 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
2efb0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
2efc0 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20  gate. ^A scalar 
2efd0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
2efe0 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
2eff0 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ntation of the x
2f000 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  Func.** callback
2f010 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e   only; NULL poin
2f020 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73  ters must be pas
2f030 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70  sed as the xStep
2f040 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70   and xFinal.** p
2f050 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61  arameters. ^An a
2f060 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
2f070 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
2f080 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
2f090 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64   of xStep.** and
2f0a0 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c   xFinal and NULL
2f0b0 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65   pointer must be
2f0c0 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e   passed for xFun
2f0d0 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e  c. ^To delete an
2f0e0 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c   existing.** SQL
2f0f0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
2f100 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c  regate, pass NUL
2f110 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61  L pointers for a
2f120 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f  ll three functio
2f130 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a  n.** callbacks..
2f140 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e  **.** ^(If the n
2f150 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  inth parameter t
2f160 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
2f170 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69  _function_v2() i
2f180 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74  s not NULL,.** t
2f190 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75  hen it is destru
2f1a0 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  ctor for the app
2f1b0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
2f1c0 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64  inter. .** The d
2f1d0 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76  estructor is inv
2f1e0 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75  oked when the fu
2f1f0 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65  nction is delete
2f200 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69  d, either by bei
2f210 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64  ng.** overloaded
2f220 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74   or when the dat
2f230 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2f240 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54   closes.)^.** ^T
2f250 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
2f260 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66   also invoked if
2f270 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
2f280 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2f290 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69  unction_v2() fai
2f2a0 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  ls..** ^When the
2f2b0 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c   destructor call
2f2c0 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74  back of the tent
2f2d0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  h parameter is i
2f2e0 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73  nvoked, it.** is
2f2f0 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65   passed a single
2f300 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
2f310 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
2f320 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
2f330 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68  a .** pointer wh
2f340 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74  ich was the fift
2f350 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2f360 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2f370 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  nction_v2()..**.
2f380 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74  ** ^It is permit
2f390 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  ted to register 
2f3a0 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
2f3b0 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
2f3c0 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  same.** function
2f3d0 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
2f3e0 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69  name but with ei
2f3f0 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e  ther differing n
2f400 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67  umbers of.** arg
2f410 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72  uments or differ
2f420 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65  ing preferred te
2f430 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e  xt encodings.  ^
2f440 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
2f450 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** the implement
2f460 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20  ation that most 
2f470 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20  closely matches 
2f480 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68  the way in which
2f490 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63   the.** SQL func
2f4a0 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e  tion is used.  ^
2f4b0 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  A function imple
2f4c0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61  mentation with a
2f4d0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a   non-negative.**
2f4e0 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20   nArg parameter 
2f4f0 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63  is a better matc
2f500 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
2f510 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
2f520 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74   with.** a negat
2f530 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75  ive nArg.  ^A fu
2f540 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
2f550 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
2f560 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63  encoding.** matc
2f570 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  hes the database
2f580 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62   encoding is a b
2f590 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74  etter.** match t
2f5a0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
2f5b0 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
2f5c0 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20  g is different. 
2f5d0 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e   .** ^A function
2f5e0 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
2f5f0 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
2f600 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c  s between UTF16l
2f610 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a  e and UTF16be.**
2f620 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74   is a closer mat
2f630 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
2f640 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
2f650 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
2f660 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55   is.** between U
2f670 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a  TF8 and UTF16..*
2f680 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66  *.** ^Built-in f
2f690 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
2f6a0 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65  overloaded by ne
2f6b0 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  w application-de
2f6c0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e  fined functions.
2f6d0 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69  .**.** ^An appli
2f6e0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2f6f0 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69  unction is permi
2f700 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68  tted to call oth
2f710 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
2f720 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65  erfaces.  Howeve
2f730 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75  r, such calls mu
2f740 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20  st not.** close 
2f750 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2f760 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61  nection nor fina
2f770 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68  lize or reset th
2f780 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  e prepared.** st
2f790 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68  atement in which
2f7a0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
2f7b0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74   running..*/.int
2f7c0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2f7d0 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69  function(.  sqli
2f7e0 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
2f7f0 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
2f800 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
2f810 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
2f820 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
2f830 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
2f840 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2f850 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2f860 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2f870 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
2f880 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2f890 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2f8a0 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
2f8b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2f8c0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2f8d0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2f8e0 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
2f8f0 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  ,.  const void *
2f900 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
2f910 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
2f920 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
2f930 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
2f940 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
2f950 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
2f960 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
2f970 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
2f980 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2f990 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2f9a0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2f9b0 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
2f9c0 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74  context*).);.int
2f9d0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2f9e0 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73  function_v2(.  s
2f9f0 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
2fa00 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
2fa10 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
2fa20 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
2fa30 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
2fa40 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
2fa50 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
2fa60 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
2fa70 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
2fa80 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
2fa90 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
2faa0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
2fab0 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
2fac0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2fad0 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  t*),.  void(*xDe
2fae0 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
2faf0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2fb00 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73  : Text Encodings
2fb10 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
2fb20 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74  stant define int
2fb30 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20  eger codes that 
2fb40 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61  represent the va
2fb50 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e  rious.** text en
2fb60 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65  codings supporte
2fb70 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  d by SQLite..*/.
2fb80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
2fb90 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a  TF8           1.
2fba0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
2fbb0 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a  TF16LE        2.
2fbc0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
2fbd0 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a  TF16BE        3.
2fbe0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
2fbf0 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20  TF16          4 
2fc00 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65     /* Use native
2fc10 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23   byte order */.#
2fc20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
2fc30 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20  Y            5  
2fc40 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
2fc50 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c  ate_function onl
2fc60 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
2fc70 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
2fc80 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74  D  8    /* sqlit
2fc90 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2fca0 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a  ion only */../*.
2fcb0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70  ** CAPI3REF: Dep
2fcc0 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e  recated Function
2fcd0 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a  s.** DEPRECATED.
2fce0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
2fcf0 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65  tions are [depre
2fd00 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65  cated].  In orde
2fd10 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a  r to maintain.**
2fd20 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
2fd30 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c  tibility with ol
2fd40 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20  der code, these 
2fd50 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e  functions contin
2fd60 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70  ue .** to be sup
2fd70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72  ported.  However
2fd80 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  , new applicatio
2fd90 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a  ns should avoid.
2fda0 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68  ** the use of th
2fdb0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
2fdc0 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67  To help encourag
2fdd0 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69  e people to avoi
2fde0 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65  d.** using these
2fdf0 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61   functions, we a
2fe00 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20  re not going to 
2fe10 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68  tell you what th
2fe20 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65  ey do..*/.#ifnde
2fe30 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45  f SQLITE_OMIT_DE
2fe40 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f  PRECATED.SQLITE_
2fe50 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
2fe60 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2fe70 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63  _count(sqlite3_c
2fe80 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45  ontext*);.SQLITE
2fe90 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
2fea0 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28  sqlite3_expired(
2feb0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2fec0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
2fed0 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72  D int sqlite3_tr
2fee0 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28  ansfer_bindings(
2fef0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73  sqlite3_stmt*, s
2ff00 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53  qlite3_stmt*);.S
2ff10 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
2ff20 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f   int sqlite3_glo
2ff30 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64  bal_recover(void
2ff40 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
2ff50 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65  ATED void sqlite
2ff60 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70  3_thread_cleanup
2ff70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44  (void);.SQLITE_D
2ff80 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
2ff90 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61  lite3_memory_ala
2ffa0 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  rm(void(*)(void*
2ffb0 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69  ,sqlite3_int64,i
2ffc0 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65  nt),void*,sqlite
2ffd0 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66  3_int64);.#endif
2ffe0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2fff0 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20  : Obtaining SQL 
30000 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74  Function Paramet
30010 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20  er Values.**.** 
30020 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69  The C-language i
30030 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
30040 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
30050 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73  nd aggregates us
30060 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f  es.** this set o
30070 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74  f interface rout
30080 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74  ines to access t
30090 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c  he parameter val
300a0 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75  ues on.** the fu
300b0 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
300c0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ate..**.** The x
300d0 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72  Func (for scalar
300e0 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78   functions) or x
300f0 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67  Step (for aggreg
30100 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73  ates) parameters
30110 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
30120 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
30130 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
30140 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
30150 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63  6()].** define c
30160 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d  allbacks that im
30170 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
30180 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
30190 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65  gregates..** The
301a0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
301b0 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b  o these callback
301c0 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  s is an array of
301d0 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20   pointers to.** 
301e0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
301f0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
30200 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65  s.  There is one
30210 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
30220 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65   object for.** e
30230 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ach parameter to
30240 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
30250 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  n.  These routin
30260 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a  es are used to.*
30270 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73  * extract values
30280 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
30290 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
302a0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s..**.** These r
302b0 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c  outines work onl
302c0 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65  y with [protecte
302d0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
302e0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79   objects..** Any
302f0 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20   attempt to use 
30300 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  these routines o
30310 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65  n an [unprotecte
30320 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
30330 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c  .** object resul
30340 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
30350 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
30360 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
30370 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74  work just like t
30380 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
30390 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
303a0 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78  functions].** ex
303b0 63 65 70 74 20 74 68 61 74 20 20 74 68 65 73 65  cept that  these
303c0 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61   routines take a
303d0 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74   single [protect
303e0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
303f0 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e  ] object.** poin
30400 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61  ter instead of a
30410 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
30420 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20   pointer and an 
30430 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e  integer column n
30440 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  umber..**.** ^Th
30450 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
30460 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61  text16() interfa
30470 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54  ce extracts a UT
30480 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69  F-16 string.** i
30490 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
304a0 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68  e-order of the h
304b0 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54  ost machine.  ^T
304c0 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  he.** sqlite3_va
304d0 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61  lue_text16be() a
304e0 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nd sqlite3_value
304f0 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65  _text16le() inte
30500 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63  rfaces.** extrac
30510 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73  t UTF-16 strings
30520 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61   as big-endian a
30530 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e  nd little-endian
30540 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
30550 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
30560 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
30570 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63  _type() interfac
30580 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70  e attempts to ap
30590 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61  ply.** numeric a
305a0 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76  ffinity to the v
305b0 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e  alue.  This mean
305c0 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70  s that an attemp
305d0 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20  t is.** made to 
305e0 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
305f0 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  e to an integer 
30600 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  or floating poin
30610 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61  t.  If.** such a
30620 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
30630 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20  ossible without 
30640 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74  loss of informat
30650 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a  ion (in other.**
30660 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76   words, if the v
30670 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67  alue is a string
30680 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65   that looks like
30690 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68   a number).** th
306a0 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  en the conversio
306b0 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20  n is performed. 
306c0 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f   Otherwise no co
306d0 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e  nversion occurs.
306e0 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
306f0 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
30700 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72  pe] after conver
30710 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64  sion is returned
30720 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65  .)^.**.** Please
30730 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20   pay particular 
30740 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65  attention to the
30750 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70   fact that the p
30760 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a  ointer returned.
30770 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
30780 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20  _value_blob()], 
30790 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
307a0 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  ext()], or.** [s
307b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
307c0 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e  t16()] can be in
307d0 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73  validated by a s
307e0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
307f0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  o.** [sqlite3_va
30800 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73  lue_bytes()], [s
30810 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
30820 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65  es16()], [sqlite
30830 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
30840 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
30850 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e  value_text16()].
30860 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
30870 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
30880 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
30890 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20  me thread as.** 
308a0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
308b0 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74   that supplied t
308c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
308d0 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a  e*] parameters..
308e0 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
308f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
30900 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  b(sqlite3_value*
30910 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
30920 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74  alue_bytes(sqlit
30930 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
30940 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
30950 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61  tes16(sqlite3_va
30960 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71  lue*);.double sq
30970 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62  lite3_value_doub
30980 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
30990 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
309a0 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65  value_int(sqlite
309b0 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74  3_value*);.sqlit
309c0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
309d0 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c  _value_int64(sql
309e0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
309f0 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
30a00 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r *sqlite3_value
30a10 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61  _text(sqlite3_va
30a20 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
30a30 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
30a40 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
30a50 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
30a60 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
30a70 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  ue_text16le(sqli
30a80 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
30a90 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
30aa0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
30ab0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
30ac0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
30ad0 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ue_type(sqlite3_
30ae0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
30af0 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
30b00 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ic_type(sqlite3_
30b10 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  value*);../*.** 
30b20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
30b30 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74   Aggregate Funct
30b40 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a  ion Context.**.*
30b50 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * Implementation
30b60 73 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53  s of aggregate S
30b70 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  QL functions use
30b80 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
30b90 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
30ba0 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ory for storing 
30bb0 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a  their state..**.
30bc0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69  ** ^The first ti
30bd0 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61  me the sqlite3_a
30be0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
30bf0 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73  (C,N) routine is
30c00 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20   called .** for 
30c10 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67  a particular agg
30c20 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c  regate function,
30c30 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63   SQLite.** alloc
30c40 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79  ates N of memory
30c50 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61  , zeroes out tha
30c60 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65  t memory, and re
30c70 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a  turns a pointer.
30c80 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65  ** to the new me
30c90 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64  mory. ^On second
30ca0 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
30cb0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
30cc0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
30cd0 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20  ntext() for the 
30ce0 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
30cf0 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
30d00 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75  ,.** the same bu
30d10 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  ffer is returned
30d20 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65  .  Sqlite3_aggre
30d30 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69  gate_context() i
30d40 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61  s normally.** ca
30d50 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61  lled once for ea
30d60 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ch invocation of
30d70 20 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62   the xStep callb
30d80 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65  ack and then one
30d90 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68  .** last time wh
30da0 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61  en the xFinal ca
30db0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
30dc0 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f  d.  ^(When no ro
30dd0 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61  ws match.** an a
30de0 67 67 72 65 67 61 74 65 20 71 75 65 72 79 2c 20  ggregate query, 
30df0 74 68 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c  the xStep() call
30e00 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72  back of the aggr
30e10 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a  egate function.*
30e20 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
30e30 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64   is never called
30e40 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73   and xFinal() is
30e50 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20   called exactly 
30e60 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73  once..** In thos
30e70 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33  e cases, sqlite3
30e80 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
30e90 78 74 28 29 20 6d 69 67 68 74 20 62 65 20 63 61  xt() might be ca
30ea0 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20  lled for the.** 
30eb0 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20  first time from 
30ec0 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e  within xFinal().
30ed0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
30ee0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
30ef0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
30f00 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e  tine returns a N
30f10 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 4e  ULL pointer if N
30f20 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e   is.** less than
30f30 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
30f40 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79  o or if a memory
30f50 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20   allocate error 
30f60 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  occurs..**.** ^(
30f70 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70  The amount of sp
30f80 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ace allocated by
30f90 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
30fa0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
30fb0 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64  is.** determined
30fc0 20 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65   by the N parame
30fd0 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63  ter on first suc
30fe0 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43  cessful call.  C
30ff0 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76  hanging the.** v
31000 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62  alue of N in sub
31010 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
31020 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
31030 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68  e_context() with
31040 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61  in.** the same a
31050 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
31060 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20  n instance will 
31070 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d  not resize the m
31080 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
31090 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51  ion.)^.**.** ^SQ
310a0 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  Lite automatical
310b0 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d  ly frees the mem
310c0 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ory allocated by
310d0 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67   .** sqlite3_agg
310e0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
310f0 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67   when the aggreg
31100 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75  ate query conclu
31110 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  des..**.** The f
31120 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d  irst parameter m
31130 75 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66  ust be a copy of
31140 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
31150 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66  _context | SQL f
31160 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d  unction context]
31170 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72   that is the fir
31180 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  st parameter.** 
31190 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72 20  to the xStep or 
311a0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20  xFinal callback 
311b0 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70  routine that imp
311c0 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72  lements the aggr
311d0 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  egate.** functio
311e0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
311f0 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
31200 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
31210 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
31220 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67  ch.** the aggreg
31230 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
31240 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
31250 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67  void *sqlite3_ag
31260 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
31270 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31280 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a  , int nBytes);..
31290 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
312a0 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75  User Data For Fu
312b0 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54  nctions.**.** ^T
312c0 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  he sqlite3_user_
312d0 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
312e0 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
312f0 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
31300 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70  r that was the p
31310 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74  UserData paramet
31320 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61  er (the 5th para
31330 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
31340 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
31350 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
31360 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
31370 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
31380 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
31390 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
313a0 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
313b0 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
313c0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
313d0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
313e0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
313f0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
31400 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
31410 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
31420 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
31430 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f  s running..*/.vo
31440 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72  id *sqlite3_user
31450 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  _data(sqlite3_co
31460 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
31470 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
31480 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f  se Connection Fo
31490 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  r Functions.**.*
314a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
314b0 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
314c0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
314d0 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
314e0 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f  * the pointer to
314f0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
31500 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20  onnection] (the 
31510 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  1st parameter).*
31520 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
31530 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
31540 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
31550 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
31560 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
31570 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
31580 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
31590 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
315a0 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
315b0 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73  n..*/.sqlite3 *s
315c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
315d0 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
315e0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a  _context*);../*.
315f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
31600 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20  ction Auxiliary 
31610 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  Data.**.** The f
31620 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e  ollowing two fun
31630 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73  ctions may be us
31640 65 64 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c  ed by scalar SQL
31650 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a   functions to.**
31660 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64   associate metad
31670 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e  ata with argumen
31680 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65  t values. If the
31690 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70   same value is p
316a0 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74  assed to.** mult
316b0 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73  iple invocations
316c0 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c   of the same SQL
316d0 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67   function during
316e0 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e   query execution
316f0 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20  , under.** some 
31700 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68  circumstances th
31710 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74  e associated met
31720 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65  adata may be pre
31730 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79  served. This may
31740 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72  .** be used, for
31750 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64   example, to add
31760 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65   a regular-expre
31770 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73  ssion matching s
31780 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  calar.** functio
31790 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20  n. The compiled 
317a0 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72  version of the r
317b0 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
317c0 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a  n is stored as.*
317d0 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  * metadata assoc
317e0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 53  iated with the S
317f0 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  QL value passed 
31800 61 73 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  as the regular e
31810 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74  xpression.** pat
31820 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69  tern.  The compi
31830 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72  led regular expr
31840 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65  ession can be re
31850 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65  used on multiple
31860 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
31870 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
31880 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65  tion so that the
31890 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72   original patter
318a0 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73  n string.** does
318b0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
318c0 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61  recompiled on ea
318d0 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a  ch invocation..*
318e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
318f0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
31900 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
31910 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
31920 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61  he metadata.** a
31930 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65  ssociated by the
31940 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
31950 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20  data() function 
31960 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67  with the Nth arg
31970 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74  ument.** value t
31980 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
31990 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
319a0 6f 6e 2e 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64  on. ^If no metad
319b0 61 74 61 20 68 61 73 20 62 65 65 6e 20 65 76 65  ata has been eve
319c0 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f  r.** been set fo
319d0 72 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65  r the Nth argume
319e0 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  nt of the functi
319f0 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f  on, or if the co
31a00 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66  rresponding.** f
31a10 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
31a20 72 20 68 61 73 20 63 68 61 6e 67 65 64 20 73 69  r has changed si
31a30 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74  nce the meta-dat
31a40 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68  a was set,.** th
31a50 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  en sqlite3_get_a
31a60 75 78 64 61 74 61 28 29 20 72 65 74 75 72 6e 73  uxdata() returns
31a70 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
31a80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
31a90 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
31aa0 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65  ) interface save
31ab0 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a  s the metadata.*
31ac0 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
31ad0 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65  its 3rd paramete
31ae0 72 20 61 73 20 74 68 65 20 6d 65 74 61 64 61 74  r as the metadat
31af0 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a  a for the N-th.*
31b00 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  * argument of th
31b10 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
31b20 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
31b30 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63   Subsequent.** c
31b40 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
31b50 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69  get_auxdata() mi
31b60 67 68 74 20 72 65 74 75 72 6e 20 74 68 69 73 20  ght return this 
31b70 64 61 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a  data, if it has.
31b80 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74  ** not been dest
31b90 72 6f 79 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74  royed..** ^If it
31ba0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51   is not NULL, SQ
31bb0 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  Lite will invoke
31bc0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a   the destructor.
31bd0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65  ** function give
31be0 6e 20 62 79 20 74 68 65 20 34 74 68 20 70 61 72  n by the 4th par
31bf0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
31c00 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
31c10 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61  on.** the metada
31c20 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72  ta when the corr
31c30 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69  esponding functi
31c40 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61  on parameter cha
31c50 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20  nges.** or when 
31c60 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
31c70 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69  t completes, whi
31c80 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72  chever comes fir
31c90 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  st..**.** SQLite
31ca0 20 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c   is free to call
31cb0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
31cc0 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74  and drop metadat
31cd0 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61  a on any.** para
31ce0 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e  meter of any fun
31cf0 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d  ction at any tim
31d00 65 2e 20 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75  e.  ^The only gu
31d10 61 72 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a  arantee is that.
31d20 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ** the destructo
31d30 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64  r will be called
31d40 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61   before the meta
31d50 64 61 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e  data is dropped.
31d60 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63  .**.** ^(In prac
31d70 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69  tice, metadata i
31d80 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77  s preserved betw
31d90 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  een function cal
31da0 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73  ls for.** expres
31db0 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63  sions that are c
31dc0 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69  onstant at compi
31dd0 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e  le time. This in
31de0 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a  cludes literal.*
31df0 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61  * values and [pa
31e00 72 61 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a  rameters].)^.**.
31e10 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
31e20 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
31e30 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
31e40 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
31e50 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
31e60 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
31e70 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
31e80 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  get_auxdata(sqli
31e90 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
31ea0 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  t N);.void sqlit
31eb0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73  e3_set_auxdata(s
31ec0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
31ed0 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76   int N, void*, v
31ee0 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b  oid (*)(void*));
31ef0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
31f00 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66  F: Constants Def
31f10 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65  ining Special De
31f20 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f  structor Behavio
31f30 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72  r.**.** These ar
31f40 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73  e special values
31f50 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63   for the destruc
31f60 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73  tor that is pass
31f70 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20  ed in as the.** 
31f80 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74  final argument t
31f90 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
31fa0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
31fb0 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68  blob()].  ^If th
31fc0 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20  e destructor.** 
31fd0 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49  argument is SQLI
31fe0 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65  TE_STATIC, it me
31ff0 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
32000 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20  tent pointer is 
32010 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20  constant.** and 
32020 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67  will never chang
32030 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20  e.  It does not 
32040 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72  need to be destr
32050 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53  oyed.  ^The.** S
32060 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
32070 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74  value means that
32080 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c   the content wil
32090 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20  l likely change 
320a0 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66  in.** the near f
320b0 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53  uture and that S
320c0 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b  QLite should mak
320d0 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  e its own privat
320e0 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  e copy of.** the
320f0 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20   content before 
32100 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  returning..**.**
32110 20 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20   The typedef is 
32120 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72  necessary to wor
32130 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d  k around problem
32140 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20  s in certain.** 
32150 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20  C++ compilers.  
32160 53 65 65 20 74 69 63 6b 65 74 20 23 32 31 39 31  See ticket #2191
32170 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69  ..*/.typedef voi
32180 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74  d (*sqlite3_dest
32190 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69  ructor_type)(voi
321a0 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c  d*);.#define SQL
321b0 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20  ITE_STATIC      
321c0 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
321d0 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65  ctor_type)0).#de
321e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
321f0 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65  SIENT   ((sqlite
32200 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
32210 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e)-1)../*.** CAP
32220 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54  I3REF: Setting T
32230 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20  he Result Of An 
32240 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a  SQL Function.**.
32250 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
32260 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68  s are used by th
32270 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61  e xFunc or xFina
32280 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  l callbacks that
32290 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51  .** implement SQ
322a0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
322b0 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65  aggregates.  See
322c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
322d0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
322e0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
322f0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
32300 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f  ].** for additio
32310 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
32320 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
32330 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79  ctions work very
32340 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b   much like the [
32350 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
32360 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  g] family of.** 
32370 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74  functions used t
32380 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  o bind values to
32390 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
323a0 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61   in prepared sta
323b0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65  tements..** Refe
323c0 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61  r to the [SQL pa
323d0 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e  rameter] documen
323e0 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74  tation for addit
323f0 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
32400 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  n..**.** ^The sq
32410 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
32420 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  b() interface se
32430 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
32440 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
32450 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
32460 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
32470 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65  BLOB whose conte
32480 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a  nt is pointed.**
32490 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e   to by the secon
324a0 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  d parameter and 
324b0 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73  which is N bytes
324c0 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73   long where N is
324d0 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61   the.** third pa
324e0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  rameter..**.** ^
324f0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
32500 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e  lt_zeroblob() in
32510 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68 65  terfaces set the
32520 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68   result of.** th
32530 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
32540 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
32550 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74  o be a BLOB cont
32560 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a  aining all zero.
32570 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62  ** bytes and N b
32580 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68  ytes in size, wh
32590 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c  ere N is the val
325a0 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61  ue of the 2nd pa
325b0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  rameter..**.** ^
325c0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
325d0 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65  lt_double() inte
325e0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
325f0 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
32600 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
32610 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
32620 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70   be a floating p
32630 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69  oint value speci
32640 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32  fied.** by its 2
32650 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
32660 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
32670 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
32680 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
32690 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63  t_error16() func
326a0 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74  tions.** cause t
326b0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53  he implemented S
326c0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74  QL function to t
326d0 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f  hrow an exceptio
326e0 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  n..** ^SQLite us
326f0 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f  es the string po
32700 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a  inted to by the.
32710 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ** 2nd parameter
32720 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75   of sqlite3_resu
32730 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71  lt_error() or sq
32740 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
32750 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65  or16().** as the
32760 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f   text of an erro
32770 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c  r message.  ^SQL
32780 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74  ite interprets t
32790 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  he error.** mess
327a0 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  age string from 
327b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
327c0 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e  rror() as UTF-8.
327d0 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65   ^SQLite.** inte
327e0 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e  rprets the strin
327f0 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72  g from sqlite3_r
32800 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
32810 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  as UTF-16 in nat
32820 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65  ive.** byte orde
32830 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69 72  r.  ^If the thir
32840 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
32850 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
32860 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ror().** or sqli
32870 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
32880 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 65  16() is negative
32890 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
328a0 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a  es as the error.
328b0 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74  ** message all t
328c0 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 74  ext up through t
328d0 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
328e0 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  aracter..** ^If 
328f0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
32900 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
32910 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72  esult_error() or
32920 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
32930 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
32940 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65  non-negative the
32950 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74  n SQLite takes t
32960 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65  hat many.** byte
32970 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
32980 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  s) from the 2nd 
32990 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
329a0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
329b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
329c0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
329d0 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
329e0 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72  t_error16().** r
329f0 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70  outines make a p
32a00 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
32a10 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
32a20 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20   text before.** 
32a30 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65  they return.  He
32a40 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  nce, the calling
32a50 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65   function can de
32a60 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d  allocate or.** m
32a70 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61  odify the text a
32a80 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e  fter they return
32a90 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a   without harm..*
32aa0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
32ab0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
32ac0 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e  () function chan
32ad0 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f  ges the error co
32ae0 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  de.** returned b
32af0 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65  y SQLite as a re
32b00 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72  sult of an error
32b10 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20   in a function. 
32b20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a   ^By default,.**
32b30 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
32b40 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  is SQLITE_ERROR.
32b50 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20    ^A subsequent 
32b60 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
32b70 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a  result_error().*
32b80 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
32b90 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65  ult_error16() re
32ba0 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 63  sets the error c
32bb0 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52  ode to SQLITE_ER
32bc0 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ROR..**.** ^The 
32bd0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
32be0 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e  rror_toobig() in
32bf0 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
32c00 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61  QLite to throw a
32c10 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63  n.** error indic
32c20 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72  ating that a str
32c30 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74  ing or BLOB is t
32c40 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65  oo long to repre
32c50 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  sent..**.** ^The
32c60 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32c70 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e  error_nomem() in
32c80 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
32c90 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61  QLite to throw a
32ca0 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63  n.** error indic
32cb0 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d  ating that a mem
32cc0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
32cd0 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ailed..**.** ^Th
32ce0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
32cf0 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65  _int() interface
32d00 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
32d10 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
32d20 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
32d30 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
32d40 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73   be the 32-bit s
32d50 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
32d60 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20   value given in 
32d70 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  the 2nd argument
32d80 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
32d90 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29  3_result_int64()
32da0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
32db0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
32dc0 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
32dd0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
32de0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
32df0 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  e 64-bit signed 
32e00 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
32e10 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
32e20 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
32e30 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
32e40 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74  esult_null() int
32e50 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
32e60 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
32e70 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
32e80 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
32e90 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a  ion to be NULL..
32ea0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
32eb0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29  e3_result_text()
32ec0 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  , sqlite3_result
32ed0 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71  _text16(),.** sq
32ee0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
32ef0 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c  t16le(), and sql
32f00 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
32f10 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65  16be() interface
32f20 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74  s.** set the ret
32f30 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65  urn value of the
32f40 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
32f50 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
32f60 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74   be.** a text st
32f70 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65  ring which is re
32f80 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46  presented as UTF
32f90 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76  -8, UTF-16 nativ
32fa0 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a  e byte order,.**
32fb0 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65   UTF-16 little e
32fc0 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36  ndian, or UTF-16
32fd0 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73   big endian, res
32fe0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53  pectively..** ^S
32ff0 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20  QLite takes the 
33000 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d  text result from
33010 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
33020 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64   from.** the 2nd
33030 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68   parameter of th
33040 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
33050 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
33060 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72  s..** ^If the 3r
33070 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
33080 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
33090 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
330a0 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76  es.** is negativ
330b0 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  e, then SQLite t
330c0 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74  akes result text
330d0 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
330e0 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75  rameter.** throu
330f0 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
33100 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  o character..** 
33110 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61  ^If the 3rd para
33120 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
33130 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
33140 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
33150 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
33160 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79   then as many by
33170 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74  tes (not charact
33180 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74  ers) of the text
33190 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
331a0 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
331b0 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73  ter are taken as
331c0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
331d0 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63  -defined.** func
331e0 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66  tion result.  If
331f0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
33200 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  er is non-negati
33210 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d  ve, then it.** m
33220 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20  ust be the byte 
33230 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20  offset into the 
33240 73 74 72 69 6e 67 20 77 68 65 72 65 20 74 68 65  string where the
33250 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20   NUL terminator 
33260 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20  would.** appear 
33270 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 77 68  if the string wh
33280 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74  ere NUL terminat
33290 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20  ed.  If any NUL 
332a0 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72  characters occur
332b0 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e  .** in the strin
332c0 67 20 61 74 20 61 20 62 79 74 65 20 6f 66 66 73  g at a byte offs
332d0 65 74 20 74 68 61 74 20 69 73 20 6c 65 73 73 20  et that is less 
332e0 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f  than the value o
332f0 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72  f the 3rd.** par
33300 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65  ameter, then the
33310 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
33320 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65  g will contain e
33330 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64  mbedded NULs and
33340 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f   the.** result o
33350 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70  f expressions op
33360 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e  erating on strin
33370 67 73 20 77 69 74 68 20 65 6d 62 65 64 64 65 64  gs with embedded
33380 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e   NULs is undefin
33390 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  ed..** ^If the 4
333a0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
333b0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
333c0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
333d0 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
333e0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
333f0 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
33400 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
33410 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66   calls that.** f
33420 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64  unction as the d
33430 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65  estructor on the
33440 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65   text or BLOB re
33450 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73  sult when it has
33460 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69  .** finished usi
33470 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
33480 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
33490 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
334a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
334b0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ext* interfaces 
334c0 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  or to.** sqlite3
334d0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
334e0 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73  the special cons
334f0 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54  tant SQLITE_STAT
33500 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a  IC, then SQLite.
33510 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ** assumes that 
33520 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42  the text or BLOB
33530 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f   result is in co
33540 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64  nstant space and
33550 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70   does not.** cop
33560 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  y the content of
33570 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e   the parameter n
33580 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75  or call a destru
33590 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74  ctor on the cont
335a0 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68  ent.** when it h
335b0 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  as finished usin
335c0 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
335d0 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
335e0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
335f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
33600 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
33610 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
33620 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20  ult_blob is the 
33630 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74  special constant
33640 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
33650 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65  T.** then SQLite
33660 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
33670 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f   the result into
33680 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20   space obtained 
33690 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  from.** from [sq
336a0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
336b0 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e  before it return
336c0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
336d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
336e0 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ue() interface s
336f0 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f  ets the result o
33700 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
33710 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
33720 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f  ction to be a co
33730 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f  py the.** [unpro
33740 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
33750 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65  alue] object spe
33760 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e  cified by the 2n
33770 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54  d parameter.  ^T
33780 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  he.** sqlite3_re
33790 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74  sult_value() int
337a0 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63  erface makes a c
337b0 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  opy of the [sqli
337c0 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f  te3_value].** so
337d0 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74   that the [sqlit
337e0 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66  e3_value] specif
337f0 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d  ied in the param
33800 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20  eter may change 
33810 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63  or.** be dealloc
33820 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74  ated after sqlit
33830 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
33840 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75  ) returns withou
33850 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70  t harm..** ^A [p
33860 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
33870 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d  _value] object m
33880 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65  ay always be use
33890 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75  d where an.** [u
338a0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
338b0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
338c0 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f   is required, so
338d0 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20   either.** kind 
338e0 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  of [sqlite3_valu
338f0 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65  e] object can be
33900 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20   used with this 
33910 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
33920 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   If these routin
33930 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  es are called fr
33940 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69  om within the di
33950 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a  fferent thread.*
33960 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63  * than the one c
33970 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70  ontaining the ap
33980 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
33990 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  d function that 
339a0 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20  received.** the 
339b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
339c0 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72  ] pointer, the r
339d0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
339e0 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  ined..*/.void sq
339f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
33a00 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
33a10 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
33a20 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
33a30 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
33a40 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
33a50 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
33a60 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69  t*, double);.voi
33a70 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
33a80 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63  _error(sqlite3_c
33a90 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
33aa0 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  har*, int);.void
33ab0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33ac0 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f  error16(sqlite3_
33ad0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
33ae0 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  void*, int);.voi
33af0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
33b00 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71  _error_toobig(sq
33b10 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
33b20 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
33b30 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
33b40 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33b50 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
33b60 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f  _result_error_co
33b70 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  de(sqlite3_conte
33b80 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  xt*, int);.void 
33b90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
33ba0 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
33bb0 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  xt*, int);.void 
33bc0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
33bd0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nt64(sqlite3_con
33be0 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69  text*, sqlite3_i
33bf0 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69  nt64);.void sqli
33c00 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
33c10 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
33c20 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
33c30 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69  result_text(sqli
33c40 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
33c50 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20  nst char*, int, 
33c60 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
33c70 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
33c80 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69  sult_text16(sqli
33c90 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
33ca0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
33cb0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
33cc0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
33cd0 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71  sult_text16le(sq
33ce0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
33cf0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
33d00 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
33d10 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
33d20 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73  esult_text16be(s
33d30 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33d40 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
33d50 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
33d60 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
33d70 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c  result_value(sql
33d80 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
33d90 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
33da0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
33db0 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ult_zeroblob(sql
33dc0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
33dd0 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
33de0 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e  PI3REF: Define N
33df0 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71  ew Collating Seq
33e00 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  uences.**.** ^Th
33e10 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64  ese functions ad
33e20 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f  d, remove, or mo
33e30 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f  dify a [collatio
33e40 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  n] associated.**
33e50 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
33e60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
33e70 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65  specified as the
33e80 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
33e90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
33ea0 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   of the collatio
33eb0 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72  n is a UTF-8 str
33ec0 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74  ing.** for sqlit
33ed0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
33ee0 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ion() and sqlite
33ef0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
33f00 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61  on_v2().** and a
33f10 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69   UTF-16 string i
33f20 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
33f30 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
33f40 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
33f50 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74  16()..** ^Collat
33f60 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63  ion names that c
33f70 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63 63  ompare equal acc
33f80 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74  ording to [sqlit
33f90 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61  e3_strnicmp()] a
33fa0 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64  re.** considered
33fb0 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20   to be the same 
33fc0 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  name..**.** ^(Th
33fd0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
33fe0 20 28 65 54 65 78 74 52 65 70 29 20 6d 75 73 74   (eTextRep) must
33ff0 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63   be one of the c
34000 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c  onstants:.** <ul
34010 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
34020 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e  E_UTF8],.** <li>
34030 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
34040 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
34050 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20  TE_UTF16BE],.** 
34060 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
34070 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  16], or.** <li> 
34080 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c  [SQLITE_UTF16_AL
34090 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  IGNED]..** </ul>
340a0 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74  )^.** ^The eText
340b0 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74  Rep argument det
340c0 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f  ermines the enco
340d0 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20  ding of strings 
340e0 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65  passed.** to the
340f0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
34100 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43  ion callback, xC
34110 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65  allback..** ^The
34120 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20   [SQLITE_UTF16] 
34130 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  and [SQLITE_UTF1
34140 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65  6_ALIGNED] value
34150 73 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a  s for eTextRep.*
34160 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20  * force strings 
34170 74 6f 20 62 65 20 55 54 46 31 36 20 77 69 74 68  to be UTF16 with
34180 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
34190 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  er..** ^The [SQL
341a0 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
341b0 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65  D] value for eTe
341c0 78 74 52 65 70 20 66 6f 72 63 65 73 20 73 74 72  xtRep forces str
341d0 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a  ings to begin.**
341e0 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65   on an even byte
341f0 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20   address..**.** 
34200 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75  ^The fourth argu
34210 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61  ment, pArg, is a
34220 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  n application da
34230 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  ta pointer that 
34240 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72  is passed.** thr
34250 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73  ough as the firs
34260 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
34270 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
34280 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  tion callback..*
34290 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20  *.** ^The fifth 
342a0 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62  argument, xCallb
342b0 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65  ack, is a pointe
342c0 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69  r to the collati
342d0 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ng function..** 
342e0 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74  ^Multiple collat
342f0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61  ing functions ca
34300 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  n be registered 
34310 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e  using the same n
34320 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20  ame but.** with 
34330 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52  different eTextR
34340 65 70 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e  ep parameters an
34350 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73  d SQLite will us
34360 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66  e whichever.** f
34370 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
34380 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e   the least amoun
34390 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66  t of data transf
343a0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66  ormation..** ^If
343b0 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61   the xCallback a
343c0 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20  rgument is NULL 
343d0 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69  then the collati
343e0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a  ng function is.*
343f0 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65  * deleted.  ^Whe
34400 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20  n all collating 
34410 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67  functions having
34420 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61   the same name a
34430 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74  re deleted,.** t
34440 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73  hat collation is
34450 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c   no longer usabl
34460 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f  e..**.** ^The co
34470 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
34480 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
34490 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70 79  oked with a copy
344a0 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a   of the pArg .**
344b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
344c0 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69  a pointer and wi
344d0 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69  th two strings i
344e0 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73  n the encoding s
344f0 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74  pecified.** by t
34500 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75  he eTextRep argu
34510 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61  ment.  The colla
34520 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ting function mu
34530 73 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20  st return an.** 
34540 69 6e 74 65 67 65 72 20 74 68 61 74 20 69 73 20  integer that is 
34550 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20  negative, zero, 
34560 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69  or positive.** i
34570 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69  f the first stri
34580 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c  ng is less than,
34590 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72   equal to, or gr
345a0 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73  eater than the s
345b0 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63  econd,.** respec
345c0 74 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61  tively.  A colla
345d0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ting function mu
345e0 73 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  st always return
345f0 20 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72   the same answer
34600 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61  .** given the sa
34610 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74  me inputs.  If t
34620 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61  wo or more colla
34630 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61  ting functions a
34640 72 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a  re registered.**
34650 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   to the same col
34660 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69  lation name (usi
34670 6e 67 20 64 69 66 66 65 72 65 6e 74 20 65 54 65  ng different eTe
34680 78 74 52 65 70 20 76 61 6c 75 65 73 29 20 74 68  xtRep values) th
34690 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67  en all.** must g
346a0 69 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e  ive an equivalen
346b0 74 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e  t answer when in
346c0 76 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69 76  voked with equiv
346d0 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a  alent strings..*
346e0 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  * The collating 
346f0 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62  function must ob
34700 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ey the following
34710 20 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20   properties for 
34720 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41  all.** strings A
34730 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a  , B, and C:.**.*
34740 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49  * <ol>.** <li> I
34750 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41  f A==B then B==A
34760 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d  ..** <li> If A==
34770 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20  B and B==C then 
34780 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66  A==C..** <li> If
34790 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67   A&lt;B THEN B&g
347a0 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  t;A..** <li> If 
347b0 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b  A&lt;B and B&lt;
347c0 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a  C then A&lt;C..*
347d0 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66  * </ol>.**.** If
347e0 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e   a collating fun
347f0 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20  ction fails any 
34800 6f 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e  of the above con
34810 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61  straints and tha
34820 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66  t.** collating f
34830 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69  unction is  regi
34840 73 74 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c  stered and used,
34850 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
34860 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  or of SQLite.** 
34870 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
34880 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34890 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
348a0 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b  n_v2() works lik
348b0 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
348c0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20  _collation().** 
348d0 77 69 74 68 20 74 68 65 20 61 64 64 69 74 69 6f  with the additio
348e0 6e 20 74 68 61 74 20 74 68 65 20 78 44 65 73 74  n that the xDest
348f0 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  roy callback is 
34900 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20  invoked on pArg 
34910 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c  when.** the coll
34920 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  ating function i
34930 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43  s deleted..** ^C
34940 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
34950 6e 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 77  ns are deleted w
34960 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65  hen they are ove
34970 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72  rridden by later
34980 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  .** calls to the
34990 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74   collation creat
349a0 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  ion functions or
349b0 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61   when the.** [da
349c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
349d0 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69  n] is closed usi
349e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ng [sqlite3_clos
349f0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  e()]..**.** ^The
34a00 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61   xDestroy callba
34a10 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e  ck is <u>not</u>
34a20 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a   called if the .
34a30 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
34a40 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
34a50 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e   function fails.
34a60 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
34a70 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  hat invoke.** sq
34a80 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
34a90 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68  lation_v2() with
34aa0 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73   a non-NULL xDes
34ab0 74 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68  troy argument sh
34ac0 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74  ould .** check t
34ad0 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 61  he return code a
34ae0 6e 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  nd dispose of th
34af0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
34b00 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68  ta pointer.** th
34b10 65 6d 73 65 6c 76 65 73 20 72 61 74 68 65 72 20  emselves rather 
34b20 74 68 61 6e 20 65 78 70 65 63 74 69 6e 67 20 53  than expecting S
34b30 51 4c 69 74 65 20 74 6f 20 64 65 61 6c 20 77 69  QLite to deal wi
34b40 74 68 20 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a  th it for them..
34b50 2a 2a 20 54 68 69 73 20 69 73 20 64 69 66 66 65  ** This is diffe
34b60 72 65 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 20  rent from every 
34b70 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
34b80 65 72 66 61 63 65 2e 20 20 54 68 65 20 69 6e 63  erface.  The inc
34b90 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69  onsistency .** i
34ba0 73 20 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 75  s unfortunate bu
34bb0 74 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e  t cannot be chan
34bc0 67 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  ged without brea
34bd0 6b 69 6e 67 20 62 61 63 6b 77 61 72 64 73 20 0a  king backwards .
34be0 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
34bf0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
34c00 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  :  [sqlite3_coll
34c10 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20  ation_needed()] 
34c20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
34c30 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
34c40 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
34c50 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
34c60 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ion(.  sqlite3*,
34c70 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a   .  const char *
34c80 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54  zName, .  int eT
34c90 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20  extRep, .  void 
34ca0 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43  *pArg,.  int(*xC
34cb0 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
34cc0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
34cd0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  t,const void*).)
34ce0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
34cf0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
34d00 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  2(.  sqlite3*, .
34d10 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
34d20 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
34d30 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70  tRep, .  void *p
34d40 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  Arg,.  int(*xCom
34d50 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
34d60 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
34d70 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20  const void*),.  
34d80 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
34d90 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  void*).);.int sq
34da0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
34db0 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69  lation16(.  sqli
34dc0 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76  te3*, .  const v
34dd0 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e  oid *zName,.  in
34de0 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
34df0 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74  oid *pArg,.  int
34e00 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
34e10 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
34e20 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
34e30 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
34e40 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e  I3REF: Collation
34e50 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b   Needed Callback
34e60 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69  s.**.** ^To avoi
34e70 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69  d having to regi
34e80 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69  ster all collati
34e90 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66  on sequences bef
34ea0 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a  ore a database.*
34eb0 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61  * can be used, a
34ec0 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b   single callback
34ed0 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
34ee0 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
34ef0 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
34f00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
34f10 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
34f20 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65  ever an undefine
34f30 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  d collation.** s
34f40 65 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69  equence is requi
34f50 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  red..**.** ^If t
34f60 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
34f70 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
34f80 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  the sqlite3_coll
34f90 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41  ation_needed() A
34fa0 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  PI,.** then it i
34fb0 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d  s passed the nam
34fc0 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20  es of undefined 
34fd0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
34fe0 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a  ces as strings.*
34ff0 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46  * encoded in UTF
35000 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  -8. ^If sqlite3_
35010 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
35020 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a  16() is used,.**
35030 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70   the names are p
35040 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20  assed as UTF-16 
35050 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76  in machine nativ
35060 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
35070 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68   ^A call to eith
35080 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c  er function repl
35090 61 63 65 73 20 74 68 65 20 65 78 69 73 74 69 6e  aces the existin
350a0 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64  g collation-need
350b0 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  ed callback..**.
350c0 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61  ** ^(When the ca
350d0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
350e0 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67  d, the first arg
350f0 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20  ument passed is 
35100 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65  a copy.** of the
35110 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
35120 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c   to sqlite3_coll
35130 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f  ation_needed() o
35140 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
35150 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
35160 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61  ).  The second a
35170 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64  rgument is the d
35180 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
35190 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72  ction.  The thir
351a0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  d argument is on
351b0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46  e of [SQLITE_UTF
351c0 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  8], [SQLITE_UTF1
351d0 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  6BE],.** or [SQL
351e0 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e  ITE_UTF16LE], in
351f0 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73  dicating the mos
35200 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d  t desirable form
35210 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   of the collatio
35220 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75  n.** sequence fu
35230 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e  nction required.
35240 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72    The fourth par
35250 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
35260 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71  me of the.** req
35270 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  uired collation 
35280 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a  sequence.)^.**.*
35290 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  * The callback f
352a0 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72  unction should r
352b0 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69  egister the desi
352c0 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73  red collation us
352d0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
352e0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
352f0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
35300 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
35310 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
35320 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
35330 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69  tion_v2()]..*/.i
35340 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
35350 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73  tion_needed(.  s
35360 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
35370 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  *, .  void(*)(vo
35380 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74  id*,sqlite3*,int
35390 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20   eTextRep,const 
353a0 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  char*).);.int sq
353b0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
353c0 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69  needed16(.  sqli
353d0 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  te3*, .  void*,.
353e0 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
353f0 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
35400 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64  xtRep,const void
35410 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 51  *).);..#ifdef SQ
35420 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f  LITE_HAS_CODEC./
35430 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
35440 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72   key for an encr
35450 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  ypted database. 
35460 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68   This routine sh
35470 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65  ould be.** calle
35480 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71  d right after sq
35490 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a  lite3_open()..**
354a0 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
354b0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
354c0 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
354d0 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
354e0 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
354f0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
35500 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71  qlite3_key(.  sq
35510 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
35520 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
35530 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
35540 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
35550 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
35560 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
35570 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  e key */.);../*.
35580 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65  ** Change the ke
35590 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74  y on an open dat
355a0 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63  abase.  If the c
355b0 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20  urrent database 
355c0 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70  is not.** encryp
355d0 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  ted, this routin
355e0 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69  e will encrypt i
355f0 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f  t.  If pNew==0 o
35600 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a  r nNew==0, the.*
35610 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65  * database is de
35620 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  crypted..**.** T
35630 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
35640 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
35650 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
35660 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
35670 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
35680 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
35690 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74  3_rekey(.  sqlit
356a0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
356b0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
356c0 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
356d0 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
356e0 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
356f0 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e  Key     /* The n
35700 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a  ew key */.);../*
35710 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
35720 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66  activation key f
35730 6f 72 20 61 20 53 45 45 20 64 61 74 61 62 61 73  or a SEE databas
35740 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61  e.  Unless .** a
35750 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f  ctivated, none o
35760 66 20 74 68 65 20 53 45 45 20 72 6f 75 74 69 6e  f the SEE routin
35770 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f  es will work..*/
35780 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63  .void sqlite3_ac
35790 74 69 76 61 74 65 5f 73 65 65 28 0a 20 20 63 6f  tivate_see(.  co
357a0 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50  nst char *zPassP
357b0 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20  hrase        /* 
357c0 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73  Activation phras
357d0 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a  e */.);.#endif..
357e0 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 45 4e  #ifdef SQLITE_EN
357f0 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a  ABLE_CEROD./*.**
35800 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74   Specify the act
35810 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20  ivation key for 
35820 61 20 43 45 52 4f 44 20 64 61 74 61 62 61 73 65  a CEROD database
35830 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63  .  Unless .** ac
35840 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66  tivated, none of
35850 20 74 68 65 20 43 45 52 4f 44 20 72 6f 75 74 69   the CEROD routi
35860 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a  nes will work..*
35870 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61  /.void sqlite3_a
35880 63 74 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20  ctivate_cerod(. 
35890 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
358a0 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20  ssPhrase        
358b0 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68  /* Activation ph
358c0 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69  rase */.);.#endi
358d0 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
358e0 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75  F: Suspend Execu
358f0 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74  tion For A Short
35900 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20   Time.**.** The 
35910 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20  sqlite3_sleep() 
35920 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
35930 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65  the current thre
35940 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78  ad to suspend ex
35950 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61  ecution.** for a
35960 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72  t least a number
35970 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
35980 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 74   specified in it
35990 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  s parameter..**.
359a0 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 74  ** If the operat
359b0 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20  ing system does 
359c0 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65  not support slee
359d0 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68 0a  p requests with.
359e0 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74  ** millisecond t
359f0 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20  ime resolution, 
35a00 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69  then the time wi
35a10 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70  ll be rounded up
35a20 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65   to.** the neare
35a30 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e  st second. The n
35a40 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
35a50 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61  conds of sleep a
35a60 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65  ctually.** reque
35a70 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70  sted from the op
35a80 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
35a90 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
35aa0 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d  * ^SQLite implem
35ab0 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66  ents this interf
35ac0 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74  ace by calling t
35ad0 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d  he xSleep().** m
35ae0 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
35af0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
35b00 73 5d 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 74  s] object.  If t
35b10 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68  he xSleep() meth
35b20 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 64 65 66  od.** of the def
35b30 61 75 6c 74 20 56 46 53 20 69 73 20 6e 6f 74 20  ault VFS is not 
35b40 69 6d 70 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72  implemented corr
35b50 65 63 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d  ectly, or not im
35b60 70 6c 65 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20  plemented at.** 
35b70 61 6c 6c 2c 20 74 68 65 6e 20 74 68 65 20 62 65  all, then the be
35b80 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
35b90 33 5f 73 6c 65 65 70 28 29 20 6d 61 79 20 64 65  3_sleep() may de
35ba0 76 69 61 74 65 20 66 72 6f 6d 20 74 68 65 20 64  viate from the d
35bb0 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e  escription.** in
35bc0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61   the previous pa
35bd0 72 61 67 72 61 70 68 73 2e 0a 2a 2f 0a 69 6e 74  ragraphs..*/.int
35be0 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69   sqlite3_sleep(i
35bf0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
35c00 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68  3REF: Name Of Th
35c10 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67  e Folder Holding
35c20 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73   Temporary Files
35c30 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73  .**.** ^(If this
35c40 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
35c50 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
35c60 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68  t to a string wh
35c70 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61  ich is.** the na
35c80 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28  me of a folder (
35c90 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79  a.k.a. directory
35ca0 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70  ), then all temp
35cb0 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63  orary files.** c
35cc0 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65  reated by SQLite
35cd0 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75   when using a bu
35ce0 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f  ilt-in [sqlite3_
35cf0 76 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69  vfs | VFS].** wi
35d00 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20  ll be placed in 
35d10 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29  that directory.)
35d20 5e 20 20 5e 49 66 20 74 68 69 73 20 76 61 72 69  ^  ^If this vari
35d30 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c  able.** is a NUL
35d40 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
35d50 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20  SQLite performs 
35d60 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20  a search for an 
35d70 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74  appropriate.** t
35d80 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69  emporary file di
35d90 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49  rectory..**.** I
35da0 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
35db0 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20   read or modify 
35dc0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e  this variable in
35dd0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a   more than one.*
35de0 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69  * thread at a ti
35df0 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73  me.  It is not s
35e00 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
35e10 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
35e20 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74  ble.** if a [dat
35e30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35e40 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  ] is being used 
35e50 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
35e60 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a   in a separate.*
35e70 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20  * thread..** It 
35e80 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74  is intended that
35e90 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62   this variable b
35ea0 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73  e set once.** as
35eb0 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73   part of process
35ec0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
35ed0 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53  and before any S
35ee0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a  QLite interface.
35ef0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65  ** routines have
35f00 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64   been called and
35f10 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
35f20 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61  ble remain uncha
35f30 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74  nged.** thereaft
35f40 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  er..**.** ^The [
35f50 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
35f60 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79  tory pragma] may
35f70 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
35f80 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a  iable and cause.
35f90 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74  ** it to point t
35fa0 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
35fb0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
35fc0 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68  malloc].  ^Furth
35fd0 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b  ermore,.** the [
35fe0 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
35ff0 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77  tory pragma] alw
36000 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74  ays assumes that
36010 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74   any string.** t
36020 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
36030 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68  e points to is h
36040 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62  eld in memory ob
36050 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
36060 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
36070 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20   and the pragma 
36080 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66  may attempt to f
36090 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a  ree that memory.
360a0 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
360b0 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63  3_free]..** Henc
360c0 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61  e, if this varia
360d0 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20  ble is modified 
360e0 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72  directly, either
360f0 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a   it should be.**
36100 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61   made NULL or ma
36110 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d  de to point to m
36120 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
36130 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
36140 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20  loc].** or else 
36150 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  the use of the [
36160 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
36170 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f  tory pragma] sho
36180 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a  uld be avoided..
36190 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
361a0 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65   Windows Runtime
361b0 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
361c0 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63   temporary direc
361d0 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74  tory must be set
361e0 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  .** prior to cal
361f0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ling [sqlite3_op
36200 65 6e 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  en] or [sqlite3_
36210 6f 70 65 6e 5f 76 32 5d 2e 20 20 4f 74 68 65 72  open_v2].  Other
36220 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a  wise, various.**
36230 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72   features that r
36240 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f  equire the use o
36250 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  f temporary file
36260 73 20 6d 61 79 20 66 61 69 6c 2e 20 20 48 65 72  s may fail.  Her
36270 65 20 69 73 20 61 6e 0a 2a 2a 20 65 78 61 6d 70  e is an.** examp
36280 6c 65 20 6f 66 20 68 6f 77 20 74 6f 20 64 6f 20  le of how to do 
36290 74 68 69 73 20 75 73 69 6e 67 20 43 2b 2b 20 77  this using C++ w
362a0 69 74 68 20 74 68 65 20 57 69 6e 64 6f 77 73 20  ith the Windows 
362b0 52 75 6e 74 69 6d 65 3a 0a 2a 2a 0a 2a 2a 20 3c  Runtime:.**.** <
362c0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
362d0 0a 2a 2a 20 4c 50 43 57 53 54 52 20 7a 50 61 74  .** LPCWSTR zPat
362e0 68 20 3d 20 57 69 6e 64 6f 77 73 3a 3a 53 74 6f  h = Windows::Sto
362f0 72 61 67 65 3a 3a 41 70 70 6c 69 63 61 74 69 6f  rage::Applicatio
36300 6e 44 61 74 61 3a 3a 43 75 72 72 65 6e 74 2d 3e  nData::Current->
36310 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 20 54  .** &nbsp;     T
36320 65 6d 70 6f 72 61 72 79 46 6f 6c 64 65 72 2d 3e  emporaryFolder->
36330 50 61 74 68 2d 3e 44 61 74 61 28 29 3b 0a 2a 2a  Path->Data();.**
36340 20 63 68 61 72 20 7a 50 61 74 68 42 75 66 26 23   char zPathBuf&#
36350 39 31 3b 4d 41 58 5f 50 41 54 48 20 2b 20 31 26  91;MAX_PATH + 1&
36360 23 39 33 3b 3b 0a 2a 2a 20 6d 65 6d 73 65 74 28  #93;;.** memset(
36370 7a 50 61 74 68 42 75 66 2c 20 30 2c 20 73 69 7a  zPathBuf, 0, siz
36380 65 6f 66 28 7a 50 61 74 68 42 75 66 29 29 3b 0a  eof(zPathBuf));.
36390 2a 2a 20 57 69 64 65 43 68 61 72 54 6f 4d 75 6c  ** WideCharToMul
363a0 74 69 42 79 74 65 28 43 50 5f 55 54 46 38 2c 20  tiByte(CP_UTF8, 
363b0 30 2c 20 7a 50 61 74 68 2c 20 2d 31 2c 20 7a 50  0, zPath, -1, zP
363c0 61 74 68 42 75 66 2c 20 73 69 7a 65 6f 66 28 7a  athBuf, sizeof(z
363d0 50 61 74 68 42 75 66 29 2c 0a 2a 2a 20 26 6e 62  PathBuf),.** &nb
363e0 73 70 3b 20 20 20 20 20 4e 55 4c 4c 2c 20 4e 55  sp;     NULL, NU
363f0 4c 4c 29 3b 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  LL);.** sqlite3_
36400 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 20 3d  temp_directory =
36410 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
36420 28 22 25 73 22 2c 20 7a 50 61 74 68 42 75 66 29  ("%s", zPathBuf)
36430 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
36440 63 6b 71 75 6f 74 65 3e 0a 2a 2f 0a 53 51 4c 49  ckquote>.*/.SQLI
36450 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a  TE_EXTERN char *
36460 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72  sqlite3_temp_dir
36470 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ectory;../*.** C
36480 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
36490 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64   The Folder Hold
364a0 69 6e 67 20 44 61 74 61 62 61 73 65 20 46 69 6c  ing Database Fil
364b0 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68  es.**.** ^(If th
364c0 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  is global variab
364d0 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  le is made to po
364e0 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20  int to a string 
364f0 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20  which is.** the 
36500 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72  name of a folder
36510 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f   (a.k.a. directo
36520 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 64 61  ry), then all da
36530 74 61 62 61 73 65 20 66 69 6c 65 73 0a 2a 2a 20  tabase files.** 
36540 73 70 65 63 69 66 69 65 64 20 77 69 74 68 20 61  specified with a
36550 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 6e 61   relative pathna
36560 6d 65 20 61 6e 64 20 63 72 65 61 74 65 64 20 6f  me and created o
36570 72 20 61 63 63 65 73 73 65 64 20 62 79 0a 2a 2a  r accessed by.**
36580 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69   SQLite when usi
36590 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 77 69  ng a built-in wi
365a0 6e 64 6f 77 73 20 5b 73 71 6c 69 74 65 33 5f 76  ndows [sqlite3_v
365b0 66 73 20 7c 20 56 46 53 5d 20 77 69 6c 6c 20 62  fs | VFS] will b
365c0 65 20 61 73 73 75 6d 65 64 0a 2a 2a 20 74 6f 20  e assumed.** to 
365d0 62 65 20 72 65 6c 61 74 69 76 65 20 74 6f 20 74  be relative to t
365e0 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e  hat directory.)^
365f0 20 5e 49 66 20 74 68 69 73 20 76 61 72 69 61 62   ^If this variab
36600 6c 65 20 69 73 20 61 20 4e 55 4c 4c 0a 2a 2a 20  le is a NULL.** 
36610 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51  pointer, then SQ
36620 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
36630 74 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 66  t all database f
36640 69 6c 65 73 20 73 70 65 63 69 66 69 65 64 0a 2a  iles specified.*
36650 2a 20 77 69 74 68 20 61 20 72 65 6c 61 74 69 76  * with a relativ
36660 65 20 70 61 74 68 6e 61 6d 65 20 61 72 65 20 72  e pathname are r
36670 65 6c 61 74 69 76 65 20 74 6f 20 74 68 65 20 63  elative to the c
36680 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
36690 0a 2a 2a 20 66 6f 72 20 74 68 65 20 70 72 6f 63  .** for the proc
366a0 65 73 73 2e 20 20 4f 6e 6c 79 20 74 68 65 20 77  ess.  Only the w
366b0 69 6e 64 6f 77 73 20 56 46 53 20 6d 61 6b 65 73  indows VFS makes
366c0 20 75 73 65 20 6f 66 20 74 68 69 73 20 67 6c 6f   use of this glo
366d0 62 61 6c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 3b  bal.** variable;
366e0 20 69 74 20 69 73 20 69 67 6e 6f 72 65 64 20 62   it is ignored b
366f0 79 20 74 68 65 20 75 6e 69 78 20 56 46 53 2e 0a  y the unix VFS..
36700 2a 2a 0a 2a 2a 20 43 68 61 6e 67 69 6e 67 20 74  **.** Changing t
36710 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  he value of this
36720 20 76 61 72 69 61 62 6c 65 20 77 68 69 6c 65 20   variable while 
36730 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
36740 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 6f 70 65 6e  ction is.** open
36750 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 61   can result in a
36760 20 63 6f 72 72 75 70 74 20 64 61 74 61 62 61 73   corrupt databas
36770 65 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e  e..**.** It is n
36780 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20  ot safe to read 
36790 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  or modify this v
367a0 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20  ariable in more 
367b0 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65  than one.** thre
367c0 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49  ad at a time.  I
367d0 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
367e0 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20   read or modify 
367f0 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a  this variable.**
36800 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20   if a [database 
36810 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62  connection] is b
36820 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65  eing used at the
36830 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20   same time in a 
36840 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65  separate.** thre
36850 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74  ad..** It is int
36860 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20  ended that this 
36870 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20  variable be set 
36880 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20  once.** as part 
36890 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  of process initi
368a0 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65  alization and be
368b0 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20  fore any SQLite 
368c0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75  interface.** rou
368d0 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20  tines have been 
368e0 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20  called and that 
368f0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65  this variable re
36900 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a  main unchanged.*
36910 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a  * thereafter..**
36920 0a 2a 2a 20 5e 54 68 65 20 5b 64 61 74 61 5f 73  .** ^The [data_s
36930 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
36940 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66  ragma] may modif
36950 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  y this variable 
36960 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20  and cause.** it 
36970 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f  to point to memo
36980 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
36990 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
369a0 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65  ].  ^Furthermore
369b0 2c 0a 2a 2a 20 74 68 65 20 5b 64 61 74 61 5f 73  ,.** the [data_s
369c0 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
369d0 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73  ragma] always as
369e0 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73  sumes that any s
369f0 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68  tring.** that th
36a00 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e  is variable poin
36a10 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e  ts to is held in
36a20 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
36a30 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74   from .** [sqlit
36a40 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74  e3_malloc] and t
36a50 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74  he pragma may at
36a60 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68  tempt to free th
36a70 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69  at memory.** usi
36a80 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
36a90 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20  ]..** Hence, if 
36aa0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73  this variable is
36ab0 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74   modified direct
36ac0 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68  ly, either it sh
36ad0 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20  ould be.** made 
36ae0 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20  NULL or made to 
36af0 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20  point to memory 
36b00 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
36b10 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a  qlite3_malloc].*
36b20 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73  * or else the us
36b30 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 5f 73  e of the [data_s
36b40 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
36b50 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65  ragma] should be
36b60 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c   avoided..*/.SQL
36b70 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20  ITE_EXTERN char 
36b80 2a 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 64 69  *sqlite3_data_di
36b90 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20  rectory;../*.** 
36ba0 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46  CAPI3REF: Test F
36bb0 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d  or Auto-Commit M
36bc0 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ode.** KEYWORDS:
36bd0 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   {autocommit mod
36be0 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e}.**.** ^The sq
36bf0 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
36c00 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65  mmit() interface
36c10 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
36c20 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20  o or.** zero if 
36c30 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61  the given databa
36c40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
36c50 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75   or is not in au
36c60 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a  tocommit mode,.*
36c70 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  * respectively. 
36c80 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   ^Autocommit mod
36c90 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75  e is on by defau
36ca0 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d  lt..** ^Autocomm
36cb0 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62  it mode is disab
36cc0 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d  led by a [BEGIN]
36cd0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e   statement..** ^
36ce0 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
36cf0 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79  is re-enabled by
36d00 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b   a [COMMIT] or [
36d10 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a  ROLLBACK]..**.**
36d20 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64   If certain kind
36d30 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75  s of errors occu
36d40 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74  r on a statement
36d50 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d   within a multi-
36d60 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61  statement.** tra
36d70 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73  nsaction (errors
36d80 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49   including [SQLI
36d90 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54  TE_FULL], [SQLIT
36da0 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51  E_IOERR],.** [SQ
36db0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51  LITE_NOMEM], [SQ
36dc0 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20  LITE_BUSY], and 
36dd0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
36de0 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  T]) then the.** 
36df0 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68  transaction migh
36e00 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  t be rolled back
36e10 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
36e20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f   The only way to
36e30 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65  .** find out whe
36e40 74 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f  ther SQLite auto
36e50 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
36e60 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61   back the transa
36e70 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61  ction after.** a
36e80 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73  n error is to us
36e90 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  e this function.
36ea0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65  .**.** If anothe
36eb0 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73  r thread changes
36ec0 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20   the autocommit 
36ed0 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61  status of the da
36ee0 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
36ef0 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20  tion while this 
36f00 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69  routine is runni
36f10 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74  ng, then the ret
36f20 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  urn value.** is 
36f30 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e  undefined..*/.in
36f40 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  t sqlite3_get_au
36f50 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33  tocommit(sqlite3
36f60 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
36f70 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61  REF: Find The Da
36f80 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66  tabase Handle Of
36f90 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
36fa0 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ement.**.** ^The
36fb0 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64   sqlite3_db_hand
36fc0 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  le interface ret
36fd0 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61  urns the [databa
36fe0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
36ff0 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63  andle.** to whic
37000 68 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  h a [prepared st
37010 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73  atement] belongs
37020 2e 20 20 5e 54 68 65 20 5b 64 61 74 61 62 61 73  .  ^The [databas
37030 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
37040 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
37050 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69  ite3_db_handle i
37060 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  s the same [data
37070 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
37080 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 74 68 65  .** that was the
37090 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a   first argument.
370a0 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
370b0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
370c0 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61   call (or its va
370d0 72 69 61 6e 74 73 29 20 74 68 61 74 20 77 61 73  riants) that was
370e0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61   used to.** crea
370f0 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
37100 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c   in the first pl
37110 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20  ace..*/.sqlite3 
37120 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64  *sqlite3_db_hand
37130 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
37140 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
37150 45 46 3a 20 52 65 74 75 72 6e 20 54 68 65 20 46  EF: Return The F
37160 69 6c 65 6e 61 6d 65 20 46 6f 72 20 41 20 44 61  ilename For A Da
37170 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
37180 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  n.**.** ^The sql
37190 69 74 65 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65  ite3_db_filename
371a0 28 44 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (D,N) interface 
371b0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
371c0 72 20 74 6f 20 61 20 66 69 6c 65 6e 61 6d 65 0a  r to a filename.
371d0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
371e0 74 68 20 64 61 74 61 62 61 73 65 20 4e 20 6f 66  th database N of
371f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20   connection D.  
37200 5e 54 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61  ^The main databa
37210 73 65 20 66 69 6c 65 0a 2a 2a 20 68 61 73 20 74  se file.** has t
37220 68 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 2e 20  he name "main". 
37230 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   If there is no 
37240 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
37250 65 20 4e 20 6f 6e 20 74 68 65 20 64 61 74 61 62  e N on the datab
37260 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
37270 6e 20 44 2c 20 6f 72 20 69 66 20 64 61 74 61 62  n D, or if datab
37280 61 73 65 20 4e 20 69 73 20 61 20 74 65 6d 70 6f  ase N is a tempo
37290 72 61 72 79 20 6f 72 20 69 6e 2d 6d 65 6d 6f 72  rary or in-memor
372a0 79 20 64 61 74 61 62 61 73 65 2c 20 74 68 65 6e  y database, then
372b0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
372c0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
372d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 6c 65 6e  **.** ^The filen
372e0 61 6d 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  ame returned by 
372f0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  this function is
37300 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 74   the output of t
37310 68 65 0a 2a 2a 20 78 46 75 6c 6c 50 61 74 68 6e  he.** xFullPathn
37320 61 6d 65 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ame method of th
37330 65 20 5b 56 46 53 5d 2e 20 20 5e 49 6e 20 6f 74  e [VFS].  ^In ot
37340 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 66  her words, the f
37350 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20  ilename.** will 
37360 62 65 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  be an absolute p
37370 61 74 68 6e 61 6d 65 2c 20 65 76 65 6e 20 69 66  athname, even if
37380 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 75 73   the filename us
37390 65 64 0a 2a 2a 20 74 6f 20 6f 70 65 6e 20 74 68  ed.** to open th
373a0 65 20 64 61 74 61 62 61 73 65 20 6f 72 69 67 69  e database origi
373b0 6e 61 6c 6c 79 20 77 61 73 20 61 20 55 52 49 20  nally was a URI 
373c0 6f 72 20 72 65 6c 61 74 69 76 65 20 70 61 74 68  or relative path
373d0 6e 61 6d 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  name..*/.const c
373e0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f  har *sqlite3_db_
373f0 66 69 6c 65 6e 61 6d 65 28 73 71 6c 69 74 65 33  filename(sqlite3
37400 20 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68 61 72   *db, const char
37410 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a   *zDbName);../*.
37420 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
37430 65 72 6d 69 6e 65 20 69 66 20 61 20 64 61 74 61  ermine if a data
37440 62 61 73 65 20 69 73 20 72 65 61 64 2d 6f 6e 6c  base is read-onl
37450 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  y.**.** ^The sql
37460 69 74 65 33 5f 64 62 5f 72 65 61 64 6f 6e 6c 79  ite3_db_readonly
37470 28 44 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (D,N) interface 
37480 72 65 74 75 72 6e 73 20 31 20 69 66 20 74 68 65  returns 1 if the
37490 20 64 61 74 61 62 61 73 65 20 4e 0a 2a 2a 20 6f   database N.** o
374a0 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 20 69  f connection D i
374b0 73 20 72 65 61 64 2d 6f 6e 6c 79 2c 20 30 20 69  s read-only, 0 i
374c0 66 20 69 74 20 69 73 20 72 65 61 64 2f 77 72 69  f it is read/wri
374d0 74 65 2c 20 6f 72 20 2d 31 20 69 66 20 4e 20 69  te, or -1 if N i
374e0 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 6e 61 6d  s not.** the nam
374f0 65 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20  e of a database 
37500 6f 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  on connection D.
37510 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
37520 64 62 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69  db_readonly(sqli
37530 74 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74 20 63  te3 *db, const c
37540 68 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a  har *zDbName);..
37550 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37560 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72  Find the next pr
37570 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
37580 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74  .**.** ^This int
37590 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
375a0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
375b0 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64 20 73  next [prepared s
375c0 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a  tatement] after.
375d0 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61  ** pStmt associa
375e0 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
375f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37600 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20 70 53 74  n] pDb.  ^If pSt
37610 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68  mt is NULL.** th
37620 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  en this interfac
37630 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
37640 74 65 72 20 74 6f 20 74 68 65 20 66 69 72 73 74  ter to the first
37650 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
37660 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ent.** associate
37670 64 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62  d with the datab
37680 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70  ase connection p
37690 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72 65 70  Db.  ^If no prep
376a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
376b0 2a 20 73 61 74 69 73 66 69 65 73 20 74 68 65 20  * satisfies the 
376c0 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74 68  conditions of th
376d0 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20 72  is routine, it r
376e0 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  eturns NULL..**.
376f0 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 61 73 65  ** The [database
37700 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69   connection] poi
37710 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c 6c  nter D in a call
37720 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
37730 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20  next_stmt(D,S)] 
37740 6d 75 73 74 20 72 65 66 65 72 20 74 6f 20 61 6e  must refer to an
37750 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a 2a   open database.*
37760 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64  * connection and
37770 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20 6d   in particular m
37780 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c  ust not be a NUL
37790 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71  L pointer..*/.sq
377a0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69  lite3_stmt *sqli
377b0 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71  te3_next_stmt(sq
377c0 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69  lite3 *pDb, sqli
377d0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
377e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
377f0 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f  F: Commit And Ro
37800 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74  llback Notificat
37810 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ion Callbacks.**
37820 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
37830 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69  _commit_hook() i
37840 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
37850 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  rs a callback.**
37860 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
37870 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
37880 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
37890 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d  s [COMMIT | comm
378a0 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20  itted]..** ^Any 
378b0 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20  callback set by 
378c0 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  a previous call 
378d0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  to sqlite3_commi
378e0 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20  t_hook().** for 
378f0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
37900 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
37910 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e  overridden..** ^
37920 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  The sqlite3_roll
37930 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65  back_hook() inte
37940 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
37950 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  a callback.** fu
37960 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76  nction to be inv
37970 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
37980 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b  transaction is [
37990 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65  ROLLBACK | rolle
379a0 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79  d back]..** ^Any
379b0 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
379c0 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
379d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c   to sqlite3_roll
379e0 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66  back_hook().** f
379f0 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
37a00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
37a10 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
37a20 2a 20 5e 54 68 65 20 70 41 72 67 20 61 72 67 75  * ^The pArg argu
37a30 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74  ment is passed t
37a40 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61  hrough to the ca
37a50 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74  llback..** ^If t
37a60 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61  he callback on a
37a70 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e   commit hook fun
37a80 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f  ction returns no
37a90 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20  n-zero,.** then 
37aa0 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f  the commit is co
37ab0 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72  nverted into a r
37ac0 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  ollback..**.** ^
37ad0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  The sqlite3_comm
37ae0 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 61  it_hook(D,C,P) a
37af0 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  nd sqlite3_rollb
37b00 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20  ack_hook(D,C,P) 
37b10 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74  functions.** ret
37b20 75 72 6e 20 74 68 65 20 50 20 61 72 67 75 6d 65  urn the P argume
37b30 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76  nt from the prev
37b40 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74 68 65  ious call of the
37b50 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a   same function.*
37b60 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  * on the same [d
37b70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37b80 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66  on] D, or NULL f
37b90 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  or.** the first 
37ba0 63 61 6c 6c 20 66 6f 72 20 65 61 63 68 20 66 75  call for each fu
37bb0 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a  nction on D..**.
37bc0 2a 2a 20 54 68 65 20 63 6f 6d 6d 69 74 20 61 6e  ** The commit an
37bd0 64 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20  d rollback hook 
37be0 63 61 6c 6c 62 61 63 6b 73 20 61 72 65 20 6e 6f  callbacks are no
37bf0 74 20 72 65 65 6e 74 72 61 6e 74 2e 0a 2a 2a 20  t reentrant..** 
37c00 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70  The callback imp
37c10 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74  lementation must
37c20 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
37c30 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
37c40 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
37c50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
37c60 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63 61  t invoked the ca
37c70 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63 74  llback.  Any act
37c80 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66  ions.** to modif
37c90 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  y the database c
37ca0 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62  onnection must b
37cb0 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c  e deferred until
37cc0 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f   after the.** co
37cd0 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20  mpletion of the 
37ce0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
37cf0 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
37d00 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a  ered the commit.
37d10 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68  ** or rollback h
37d20 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73 74  ook in the first
37d30 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20   place..** Note 
37d40 74 68 61 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  that running any
37d50 20 6f 74 68 65 72 20 53 51 4c 20 73 74 61 74 65   other SQL state
37d60 6d 65 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67  ments, including
37d70 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
37d80 74 73 2c 0a 2a 2a 20 6f 72 20 6d 65 72 65 6c 79  ts,.** or merely
37d90 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
37da0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
37db0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
37dc0 70 28 29 5d 20 77 69 6c 6c 20 6d 6f 64 69 66 79  p()] will modify
37dd0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
37de0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
37df0 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
37e00 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
37e10 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
37e20 2a 20 5e 52 65 67 69 73 74 65 72 69 6e 67 20 61  * ^Registering a
37e30 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64   NULL function d
37e40 69 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c  isables the call
37e50 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  back..**.** ^Whe
37e60 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f  n the commit hoo
37e70 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  k callback routi
37e80 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c  ne returns zero,
37e90 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a   the [COMMIT].**
37ea0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6c   operation is al
37eb0 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75  lowed to continu
37ec0 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49 66  e normally.  ^If
37ed0 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b   the commit hook
37ee0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  .** returns non-
37ef0 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b  zero, then the [
37f00 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65  COMMIT] is conve
37f10 72 74 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c  rted into a [ROL
37f20 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20  LBACK]..** ^The 
37f30 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73  rollback hook is
37f40 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f   invoked on a ro
37f50 6c 6c 62 61 63 6b 20 74 68 61 74 20 72 65 73 75  llback that resu
37f60 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69  lts from a commi
37f70 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e  t.** hook return
37f80 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75  ing non-zero, ju
37f90 73 74 20 61 73 20 69 74 20 77 6f 75 6c 64 20 62  st as it would b
37fa0 65 20 77 69 74 68 20 61 6e 79 20 6f 74 68 65 72  e with any other
37fb0 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   rollback..**.**
37fc0 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73   ^For the purpos
37fd0 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20  es of this API, 
37fe0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
37ff0 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 65   said to have be
38000 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63  en.** rolled bac
38010 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74  k if an explicit
38020 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74   "ROLLBACK" stat
38030 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74 65  ement is execute
38040 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f  d, or.** an erro
38050 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20  r or constraint 
38060 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63  causes an implic
38070 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f  it rollback to o
38080 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f  ccur..** ^The ro
38090 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20  llback callback 
380a0 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69  is not invoked i
380b0 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  f a transaction 
380c0 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  is.** automatica
380d0 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  lly rolled back 
380e0 62 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61  because the data
380f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
38100 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  is closed..**.**
38110 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
38120 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
38130 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ok()] interface.
38140 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
38150 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71  3_commit_hook(sq
38160 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76  lite3*, int(*)(v
38170 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76  oid*), void*);.v
38180 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c  oid *sqlite3_rol
38190 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74  lback_hook(sqlit
381a0 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  e3*, void(*)(voi
381b0 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  d *), void*);../
381c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
381d0 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66  ata Change Notif
381e0 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ication Callback
381f0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
38200 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
38210 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  () interface reg
38220 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
38230 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69  k function.** wi
38240 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
38250 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65   connection] ide
38260 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ntified by the f
38270 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  irst argument.**
38280 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
38290 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73  henever a row is
382a0 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74   updated, insert
382b0 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a  ed or deleted..*
382c0 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  * ^Any callback 
382d0 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
382e0 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66  s call to this f
382f0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74  unction.** for t
38300 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
38310 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
38320 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a  verridden..**.**
38330 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
38340 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
38350 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69  er to the functi
38360 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65  on to invoke whe
38370 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70  n a.** row is up
38380 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20  dated, inserted 
38390 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e  or deleted..** ^
383a0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
383b0 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  nt to the callba
383c0 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
383d0 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
383e0 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  nt.** to sqlite3
383f0 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a  _update_hook()..
38400 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 63  ** ^The second c
38410 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74  allback argument
38420 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
38430 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c  TE_INSERT], [SQL
38440 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20  ITE_DELETE],.** 
38450 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54  or [SQLITE_UPDAT
38460 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  E], depending on
38470 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74   the operation t
38480 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20 63  hat caused the c
38490 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65  allback.** to be
384a0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68   invoked..** ^Th
384b0 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  e third and four
384c0 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  th arguments to 
384d0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  the callback con
384e0 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f  tain pointers to
384f0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
38500 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d 65 20   and table name 
38510 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
38520 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20  ffected row..** 
38530 5e 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62  ^The final callb
38540 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73  ack parameter is
38550 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
38560 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49 6e 20  the row..** ^In 
38570 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75  the case of an u
38580 70 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 74  pdate, this is t
38590 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 74 65 72  he [rowid] after
385a0 20 74 68 65 20 75 70 64 61 74 65 20 74 61 6b 65   the update take
385b0 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e  s place..**.** ^
385c0 28 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b  (The update hook
385d0 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
385e0 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79  when internal sy
385f0 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a  stem tables are.
38600 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65  ** modified (i.e
38610 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20  . sqlite_master 
38620 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65  and sqlite_seque
38630 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49  nce).)^.**.** ^I
38640 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d  n the current im
38650 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68  plementation, th
38660 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a  e update hook.**
38670 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
38680 77 68 65 6e 20 64 75 70 6c 69 63 61 74 69 6f 6e  when duplication
38690 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
386a0 64 20 62 65 63 61 75 73 65 20 6f 66 20 61 6e 0a  d because of an.
386b0 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 20  ** [ON CONFLICT 
386c0 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 52 45  | ON CONFLICT RE
386d0 50 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e 20 20  PLACE] clause.  
386e0 5e 4e 6f 72 20 69 73 20 74 68 65 20 75 70 64 61  ^Nor is the upda
386f0 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b  te hook.** invok
38700 65 64 20 77 68 65 6e 20 72 6f 77 73 20 61 72 65  ed when rows are
38710 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20 74   deleted using t
38720 68 65 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74  he [truncate opt
38730 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54  imization]..** T
38740 68 65 20 65 78 63 65 70 74 69 6f 6e 73 20 64 65  he exceptions de
38750 66 69 6e 65 64 20 69 6e 20 74 68 69 73 20 70 61  fined in this pa
38760 72 61 67 72 61 70 68 20 6d 69 67 68 74 20 63 68  ragraph might ch
38770 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65  ange in a future
38780 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53  .** release of S
38790 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
387a0 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 6d 70   update hook imp
387b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74  lementation must
387c0 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
387d0 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
387e0 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
387f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
38800 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 75 70  t invoked the up
38810 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 20  date hook.  Any 
38820 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f  actions.** to mo
38830 64 69 66 79 20 74 68 65 20 64