/ Hex Artifact Content
Login

Artifact a63edec76cca981ce859b5cfa4776121b7a113e5:


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 74 68  ust not close th
3e90: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
3ea0: 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
3eb0: 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65  d by.**      the
3ec0: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
3ed0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3ee0: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3ef0: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3f00: 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  ..** <li> The ap
3f10: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
3f20: 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51  ot modify the SQ
3f30: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
3f40: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
3f50: 20 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72       the 2nd par
3f60: 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
3f70: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
3f80: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3f90: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75   running..** </u
3fa0: 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l>.*/.int sqlite
3fb0: 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65  3_exec(.  sqlite
3fc0: 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  3*,             
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fe0: 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20       /* An open 
3ff0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
4000: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20  nst 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 20 20 20 20 2f 2a 20 53 51 4c 20           /* SQL 
4030: 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
4040: 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62  */.  int (*callb
4050: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  ack)(void*,int,c
4060: 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20  har**,char**),  
4070: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63  /* Callback func
4080: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
4090: 2c 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 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75       /* 1st argu
40c0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b  ment to callback
40d0: 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72   */.  char **err
40e0: 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20  msg             
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4100: 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
4110: 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
4120: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
4130: 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  : Result Codes.*
4140: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
4150: 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64  TE_OK {error cod
4160: 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d  e} {error codes}
4170: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72  .** KEYWORDS: {r
4180: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73  esult code} {res
4190: 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a  ult codes}.**.**
41a0: 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e   Many SQLite fun
41b0: 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e  ctions return an
41c0: 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20   integer result 
41d0: 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65  code from the se
41e0: 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20  t shown.** here 
41f0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69  in order to indi
4200: 63 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20  cate success or 
4210: 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e  failure..**.** N
4220: 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d  ew error codes m
4230: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
4240: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
4250: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
4260: 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
4270: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
4280: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4290: 6f 64 65 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  odes],.** [sqlit
42a0: 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c  e3_vtab_on_confl
42b0: 69 63 74 28 29 5d 20 5b 53 51 4c 49 54 45 5f 52  ict()] [SQLITE_R
42c0: 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 73 75 6c 74  OLLBACK | result
42d0: 20 63 6f 64 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66   codes]..*/.#def
42e0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20  ine SQLITE_OK   
42f0: 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53          0   /* S
4300: 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74  uccessful result
4310: 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67   */./* beginning
4320: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
4330: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4340: 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31  E_ERROR        1
4350: 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20     /* SQL error 
4360: 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62  or missing datab
4370: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
4380: 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20  QLITE_INTERNAL  
4390: 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e     2   /* Intern
43a0: 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69  al logic error i
43b0: 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66  n SQLite */.#def
43c0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20  ine SQLITE_PERM 
43d0: 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41          3   /* A
43e0: 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e  ccess permission
43f0: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69   denied */.#defi
4400: 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ne SQLITE_ABORT 
4410: 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61         4   /* Ca
4420: 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72  llback routine r
4430: 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72  equested an abor
4440: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4450: 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20  ITE_BUSY        
4460: 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61   5   /* The data
4470: 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63  base file is loc
4480: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ked */.#define S
4490: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20  QLITE_LOCKED    
44a0: 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c     6   /* A tabl
44b0: 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  e in the databas
44c0: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23  e is locked */.#
44d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
44e0: 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f  MEM        7   /
44f0: 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69  * A malloc() fai
4500: 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  led */.#define S
4510: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20  QLITE_READONLY  
4520: 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70     8   /* Attemp
4530: 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61  t to write a rea
4540: 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a  donly database *
4550: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4560: 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20  _INTERRUPT    9 
4570: 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74    /* Operation t
4580: 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c  erminated by sql
4590: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
45a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
45b0: 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30  E_IOERR       10
45c0: 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20     /* Some kind 
45d0: 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f  of disk I/O erro
45e0: 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64  r occurred */.#d
45f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52  efine SQLITE_COR
4600: 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a  RUPT     11   /*
4610: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69   The database di
4620: 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66  sk image is malf
4630: 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ormed */.#define
4640: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
4650: 20 20 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e      12   /* Unkn
4660: 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71  own opcode in sq
4670: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
4680: 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ol() */.#define 
4690: 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20  SQLITE_FULL     
46a0: 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72     13   /* Inser
46b0: 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61  tion failed beca
46c0: 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73 20  use database is 
46d0: 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  full */.#define 
46e0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
46f0: 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c     14   /* Unabl
4700: 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  e to open the da
4710: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
4720: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
4730: 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f  OTOCOL    15   /
4740: 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20  * Database lock 
4750: 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a  protocol error *
4760: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4770: 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20  _EMPTY       16 
4780: 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73    /* Database is
4790: 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e   empty */.#defin
47a0: 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20  e SQLITE_SCHEMA 
47b0: 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65       17   /* The
47c0: 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
47d0: 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66   changed */.#def
47e0: 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49  ine SQLITE_TOOBI
47f0: 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53  G      18   /* S
4800: 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78  tring or BLOB ex
4810: 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74  ceeds size limit
4820: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4830: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31  TE_CONSTRAINT  1
4840: 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65  9   /* Abort due
4850: 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76   to constraint v
4860: 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66  iolation */.#def
4870: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41  ine SQLITE_MISMA
4880: 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44  TCH    20   /* D
4890: 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63  ata type mismatc
48a0: 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  h */.#define SQL
48b0: 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20  ITE_MISUSE      
48c0: 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20  21   /* Library 
48d0: 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  used incorrectly
48e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
48f0: 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32  TE_NOLFS       2
4900: 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66  2   /* Uses OS f
4910: 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70  eatures not supp
4920: 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f  orted on host */
4930: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4940: 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20  AUTH        23  
4950: 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f   /* Authorizatio
4960: 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66  n denied */.#def
4970: 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41  ine SQLITE_FORMA
4980: 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41  T      24   /* A
4990: 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73  uxiliary databas
49a0: 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a  e format error *
49b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
49c0: 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20  _RANGE       25 
49d0: 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74    /* 2nd paramet
49e0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
49f0: 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  nd out of range 
4a00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4a10: 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36  E_NOTADB      26
4a20: 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65     /* File opene
4a30: 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20  d that is not a 
4a40: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f  database file */
4a50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4a60: 4e 4f 54 49 43 45 20 20 20 20 20 20 32 37 20 20  NOTICE      27  
4a70: 20 2f 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e   /* Notification
4a80: 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c  s from sqlite3_l
4a90: 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  og() */.#define 
4aa0: 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 20  SQLITE_WARNING  
4ab0: 20 20 20 32 38 20 20 20 2f 2a 20 57 61 72 6e 69     28   /* Warni
4ac0: 6e 67 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ngs from sqlite3
4ad0: 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e  _log() */.#defin
4ae0: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20  e SQLITE_ROW    
4af0: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c       100  /* sql
4b00: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
4b10: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64  another row read
4b20: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4b30: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20  ITE_DONE        
4b40: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  101  /* sqlite3_
4b50: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73  step() has finis
4b60: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f  hed executing */
4b70: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72  ./* end-of-error
4b80: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  -codes */../*.**
4b90: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e   CAPI3REF: Exten
4ba0: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
4bb0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
4bc0: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
4bd0: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72  de} {extended er
4be0: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
4bf0: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65  YWORDS: {extende
4c00: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b  d result code} {
4c10: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4c20: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  codes}.**.** In 
4c30: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4c40: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4c50: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4c60: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20  eturn one of 26 
4c70: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49  integer.** [SQLI
4c80: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63  TE_OK | result c
4c90: 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c  odes].  However,
4ca0: 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20   experience has 
4cb0: 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20  shown that many 
4cc0: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75  of.** these resu
4cd0: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f  lt codes are too
4ce0: 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e   coarse-grained.
4cf0: 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72    They do not pr
4d00: 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68  ovide as.** much
4d10: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
4d20: 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70  ut problems as p
4d30: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74  rogrammers might
4d40: 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66   like.  In an ef
4d50: 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65  fort to.** addre
4d60: 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76  ss this, newer v
4d70: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4d80: 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38  e (version 3.3.8
4d90: 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c   and later) incl
4da0: 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66  ude.** support f
4db0: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65  or additional re
4dc0: 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20  sult codes that 
4dd0: 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74  provide more det
4de0: 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f  ailed informatio
4df0: 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72  n.** about error
4e00: 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20  s. The extended 
4e10: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4e20: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
4e30: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72  bled.** on a per
4e40: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
4e50: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67  tion basis using
4e60: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
4e70: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
4e80: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a  _codes()] API..*
4e90: 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65  *.** Some of the
4ea0: 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e   available exten
4eb0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4ec0: 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65   are listed here
4ed0: 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70  ..** One may exp
4ee0: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ect the number o
4ef0: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  f extended resul
4f00: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 69 6e 63  t codes will inc
4f10: 72 65 61 73 65 0a 2a 2a 20 6f 76 65 72 20 74 69  rease.** over ti
4f20: 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  me.  Software th
4f30: 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65 64  at uses extended
4f40: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68   result codes sh
4f50: 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74  ould expect.** t
4f60: 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74  o see new result
4f70: 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65   codes in future
4f80: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
4f90: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  ite..**.** The S
4fa0: 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20  QLITE_OK result 
4fb0: 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  code will never 
4fc0: 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74  be extended.  It
4fd0: 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20   will always.** 
4fe0: 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e  be exactly zero.
4ff0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5000: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20  TE_IOERR_READ   
5010: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5020: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38  TE_IOERR | (1<<8
5030: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5040: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
5050: 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  AD        (SQLIT
5060: 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29  E_IOERR | (2<<8)
5070: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5080: 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20  _IOERR_WRITE    
5090: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
50a0: 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29  _IOERR | (3<<8))
50b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
50c0: 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20  IOERR_FSYNC     
50d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
50e0: 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a  IOERR | (4<<8)).
50f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5100: 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20  OERR_DIR_FSYNC  
5110: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5120: 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23  OERR | (5<<8)).#
5130: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5140: 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20  ERR_TRUNCATE    
5150: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5160: 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  ERR | (6<<8)).#d
5170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5180: 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20  RR_FSTAT        
5190: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
51a0: 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65  RR | (7<<8)).#de
51b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
51c0: 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_UNLOCK        
51d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
51e0: 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  R | (8<<8)).#def
51f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5200: 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  _RDLOCK         
5210: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5220: 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69   | (9<<8)).#defi
5230: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5240: 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
5250: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5260: 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (10<<8)).#defi
5270: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5280: 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20  BLOCKED         
5290: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
52a0: 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (11<<8)).#defi
52b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
52c0: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20  NOMEM           
52d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
52e0: 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (12<<8)).#defi
52f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5300: 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20 20  ACCESS          
5310: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5320: 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (13<<8)).#defi
5330: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5340: 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43  CHECKRESERVEDLOC
5350: 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20  K (SQLITE_IOERR 
5360: 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (14<<8)).#defi
5370: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5380: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
5390: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
53a0: 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (15<<8)).#defi
53b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
53c0: 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 20  CLOSE           
53d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
53e0: 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (16<<8)).#defi
53f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5400: 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20  DIR_CLOSE       
5410: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5420: 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69  | (17<<8)).#defi
5430: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5440: 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20  SHMOPEN         
5450: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5460: 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69  | (18<<8)).#defi
5470: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5480: 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20  SHMSIZE         
5490: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
54a0: 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69  | (19<<8)).#defi
54b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
54c0: 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  SHMLOCK         
54d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
54e0: 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (20<<8)).#defi
54f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5500: 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20  SHMMAP          
5510: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5520: 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (21<<8)).#defi
5530: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5540: 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 20  SEEK            
5550: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5560: 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (22<<8)).#defi
5570: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5580: 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20  DELETE_NOENT    
5590: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
55a0: 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (23<<8)).#defi
55b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
55c0: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20  MMAP            
55d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
55e0: 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (24<<8)).#defi
55f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5600: 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20 20  GETTEMPPATH     
5610: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5620: 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (25<<8)).#defi
5630: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5640: 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 20  CONVPATH        
5650: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5660: 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (26<<8)).#defi
5670: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44  ne SQLITE_LOCKED
5680: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
5690: 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44    (SQLITE_LOCKED
56a0: 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66   |  (1<<8)).#def
56b0: 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f  ine SQLITE_BUSY_
56c0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 20  RECOVERY        
56d0: 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20     (SQLITE_BUSY 
56e0: 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65    |  (1<<8)).#de
56f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5700: 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20 20  _SNAPSHOT       
5710: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5720: 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64     |  (2<<8)).#d
5730: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5740: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20  TOPEN_NOTEMPDIR 
5750: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5760: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a  TOPEN | (1<<8)).
5770: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5780: 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20  ANTOPEN_ISDIR   
5790: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
57a0: 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29  ANTOPEN | (2<<8)
57b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
57c0: 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41  _CANTOPEN_FULLPA
57d0: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
57e0: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c  _CANTOPEN | (3<<
57f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5800: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56  TE_CANTOPEN_CONV
5810: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
5820: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34  TE_CANTOPEN | (4
5830: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5840: 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41  LITE_CORRUPT_VTA
5850: 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  B            (SQ
5860: 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28  LITE_CORRUPT | (
5870: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5880: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52  QLITE_READONLY_R
5890: 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 53  ECOVERY       (S
58a0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
58b0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
58c0: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
58d0: 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20  _CANTLOCK       
58e0: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
58f0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5900: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5910: 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20  LY_ROLLBACK     
5920: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5930: 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  LY | (3<<8)).#de
5940: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52  fine SQLITE_ABOR
5950: 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20  T_ROLLBACK      
5960: 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f 52      (SQLITE_ABOR
5970: 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  T | (2<<8)).#def
5980: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5990: 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 20 20  RAINT_CHECK     
59a0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
59b0: 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a  RAINT | (1<<8)).
59c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
59d0: 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54  ONSTRAINT_COMMIT
59e0: 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f 43  HOOK   (SQLITE_C
59f0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c  ONSTRAINT | (2<<
5a00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5a10: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f  TE_CONSTRAINT_FO
5a20: 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51 4c 49  REIGNKEY   (SQLI
5a30: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5a40: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
5a50: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5a60: 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 28  T_FUNCTION     (
5a70: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5a80: 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66  T | (4<<8)).#def
5a90: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5aa0: 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20  RAINT_NOTNULL   
5ab0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5ac0: 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a  RAINT | (5<<8)).
5ad0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5ae0: 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d 41 52  ONSTRAINT_PRIMAR
5af0: 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43  YKEY   (SQLITE_C
5b00: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c  ONSTRAINT | (6<<
5b10: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5b20: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52  TE_CONSTRAINT_TR
5b30: 49 47 47 45 52 20 20 20 20 20 20 28 53 51 4c 49  IGGER      (SQLI
5b40: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5b50: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (7<<8)).#define 
5b60: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b70: 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20 28  T_UNIQUE       (
5b80: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b90: 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  T | (8<<8)).#def
5ba0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5bb0: 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20 20 20  RAINT_VTAB      
5bc0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5bd0: 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a  RAINT | (9<<8)).
5be0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5bf0: 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49 44 20  ONSTRAINT_ROWID 
5c00: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5c10: 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c  ONSTRAINT |(10<<
5c20: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5c30: 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45  TE_NOTICE_RECOVE
5c40: 52 5f 57 41 4c 20 20 20 20 20 20 28 53 51 4c 49  R_WAL      (SQLI
5c50: 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c  TE_NOTICE | (1<<
5c60: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5c70: 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45  TE_NOTICE_RECOVE
5c80: 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49  R_ROLLBACK (SQLI
5c90: 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c  TE_NOTICE | (2<<
5ca0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5cb0: 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49  TE_WARNING_AUTOI
5cc0: 4e 44 45 58 20 20 20 20 20 20 20 28 53 51 4c 49  NDEX       (SQLI
5cd0: 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c  TE_WARNING | (1<
5ce0: 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  <8))../*.** CAPI
5cf0: 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20  3REF: Flags For 
5d00: 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74  File Open Operat
5d10: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
5d20: 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20   bit values are 
5d30: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
5d40: 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70   in the.** 3rd p
5d50: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
5d60: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
5d70: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e  ()] interface an
5d80: 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20  d.** in the 4th 
5d90: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
5da0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
5db0: 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a  pen] method..*/.
5dc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5dd0: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  PEN_READONLY    
5de0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 20       0x00000001 
5df0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5e00: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5e10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5e20: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20  PEN_READWRITE   
5e30: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 20       0x00000002 
5e40: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5e50: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5e60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5e70: 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20  PEN_CREATE      
5e80: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 20       0x00000004 
5e90: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5ea0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5eb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5ec0: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
5ed0: 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38 20  E    0x00000008 
5ee0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5ef0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5f00: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20  PEN_EXCLUSIVE   
5f10: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 20       0x00000010 
5f20: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5f30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5f40: 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20  PEN_AUTOPROXY   
5f50: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 20       0x00000020 
5f60: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5f70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5f80: 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20  PEN_URI         
5f90: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 20       0x00000040 
5fa0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5fb0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5fc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5fd0: 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20  PEN_MEMORY      
5fe0: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 20       0x00000080 
5ff0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6000: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6010: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6020: 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20  PEN_MAIN_DB     
6030: 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 20       0x00000100 
6040: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6050: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6060: 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20  PEN_TEMP_DB     
6070: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 20       0x00000200 
6080: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6090: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
60a0: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42  PEN_TRANSIENT_DB
60b0: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 20       0x00000400 
60c0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
60d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
60e0: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
60f0: 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30 20       0x00000800 
6100: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6110: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6120: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
6130: 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30 20       0x00001000 
6140: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6150: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6160: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20  PEN_SUBJOURNAL  
6170: 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 20       0x00002000 
6180: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6190: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
61a0: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
61b0: 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 20  AL   0x00004000 
61c0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
61d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
61e0: 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20  PEN_NOMUTEX     
61f0: 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30 20       0x00008000 
6200: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6210: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6220: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6230: 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20  PEN_FULLMUTEX   
6240: 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30 20       0x00010000 
6250: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6260: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6270: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6280: 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
6290: 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30 20       0x00020000 
62a0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
62b0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
62c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
62d0: 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
62e0: 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30 20       0x00040000 
62f0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6300: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6310: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6320: 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20  PEN_WAL         
6330: 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30 20       0x00080000 
6340: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6350: 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20  ./* Reserved:   
6360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6370: 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30 30        0x00F00000
6380: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
6390: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72  REF: Device Char
63a0: 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a  acteristics.**.*
63b0: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61  * The xDeviceCha
63c0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
63d0: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
63e0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
63f0: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
6400: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
6410: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
6420: 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76  f these.** bit v
6430: 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67  alues expressing
6440: 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73   I/O characteris
6450: 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73  tics of the mass
6460: 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69   storage.** devi
6470: 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68  ce that holds th
6480: 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20  e file that the 
6490: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
64a0: 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74  ods].** refers t
64b0: 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  o..**.** The SQL
64c0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
64d0: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
64e0: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
64f0: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
6500: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
6510: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6520: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
6530: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
6540: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
6550: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
6560: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
6570: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
6580: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
6590: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
65a0: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
65b0: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
65c0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
65d0: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
65e0: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
65f0: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
6600: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
6610: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
6620: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
6630: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
6640: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
6650: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
6660: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
6670: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6680: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
6690: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
66a0: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
66b0: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
66c0: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
66d0: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
66e0: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20  ** to xWrite(). 
66f0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6700: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
6710: 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d  WRITE property m
6720: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74  eans that.** aft
6730: 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77  er reboot follow
6740: 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20 70  ing a crash or p
6750: 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f  ower loss, the o
6760: 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a  nly bytes in a.*
6770: 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72 65  * file that were
6780: 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65 20   written at the 
6790: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65  application leve
67a0: 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68 61  l might have cha
67b0: 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74  nged.** and that
67c0: 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c   adjacent bytes,
67d0: 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74 68   even bytes with
67e0: 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63 74  in the same sect
67f0: 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e  or are.** guaran
6800: 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61  teed to be uncha
6810: 6e 67 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  nged..*/.#define
6820: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6830: 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20  OMIC            
6840: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a       0x00000001.
6850: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6860: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20  OCAP_ATOMIC512  
6870: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6880: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  000002.#define S
6890: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
68a0: 49 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC1K            
68b0: 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64     0x00000004.#d
68c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
68d0: 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20  AP_ATOMIC2K     
68e0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
68f0: 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c  0008.#define SQL
6900: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6910: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
6920: 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66   0x00000010.#def
6930: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6940: 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20  _ATOMIC8K       
6950: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6960: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  20.#define SQLIT
6970: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
6980: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
6990: 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e  x00000040.#defin
69a0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
69b0: 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20  TOMIC32K        
69c0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
69d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
69e0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20  IOCAP_ATOMIC64K 
69f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6a00: 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20  0000100.#define 
6a10: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
6a20: 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20  E_APPEND        
6a30: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23      0x00000200.#
6a40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6a50: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20  CAP_SEQUENTIAL  
6a60: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6a70: 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00400.#define SQ
6a80: 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c  LITE_IOCAP_UNDEL
6a90: 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e  ETABLE_WHEN_OPEN
6aa0: 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65    0x00000800.#de
6ab0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6ac0: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
6ad0: 57 52 49 54 45 20 20 20 20 30 78 30 30 30 30 31  WRITE    0x00001
6ae0: 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  000../*.** CAPI3
6af0: 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e  REF: File Lockin
6b00: 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53  g Levels.**.** S
6b10: 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f  QLite uses one o
6b20: 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
6b30: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
6b40: 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  cond.** argument
6b50: 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b   to calls it mak
6b60: 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28  es to the xLock(
6b70: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
6b80: 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e  methods.** of an
6b90: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6ba0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  hods] object..*/
6bb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6bc0: 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20  LOCK_NONE       
6bd0: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
6be0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20  ITE_LOCK_SHARED 
6bf0: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
6c00: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53   SQLITE_LOCK_RES
6c10: 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65  ERVED      2.#de
6c20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6c30: 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33  _PENDING       3
6c40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6c50: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20  LOCK_EXCLUSIVE  
6c60: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
6c70: 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a  3REF: Synchroniz
6c80: 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73  ation Type Flags
6c90: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
6ca0: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
6cb0: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
6cc0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
6cd0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6ce0: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
6cf0: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
6d00: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
6d10: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
6d20: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
6d30: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
6d40: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
6d50: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
6d60: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
6d70: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
6d80: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
6d90: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
6da0: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
6db0: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
6dc0: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
6dd0: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f  ushed. If the lo
6de0: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66  wer four bits of
6df0: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75   the flag.** equ
6e00: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  al SQLITE_SYNC_N
6e10: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e  ORMAL, that mean
6e20: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  s to use normal 
6e30: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
6e40: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77  s..** If the low
6e50: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75  er four bits equ
6e60: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  al SQLITE_SYNC_F
6e70: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ULL, that means.
6e80: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
6e90: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
6ea0: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
6eb0: 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e  nc()..**.** Do n
6ec0: 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53  ot confuse the S
6ed0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
6ee0: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
6ef0: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20  C_FULL flags.** 
6f00: 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41  with the [PRAGMA
6f10: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f   synchronous]=NO
6f20: 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41  RMAL and [PRAGMA
6f30: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55   synchronous]=FU
6f40: 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20  LL.** settings. 
6f50: 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75   The [synchronou
6f60: 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d  s pragma] determ
6f70: 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20  ines when calls 
6f80: 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20  to the.** xSync 
6f90: 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72  VFS method occur
6fa0: 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69   and applies uni
6fb0: 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c  formly across al
6fc0: 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20  l platforms..** 
6fd0: 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  The SQLITE_SYNC_
6fe0: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
6ff0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
7000: 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a  s determine how.
7010: 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20  ** energetic or 
7020: 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63  rigorous or forc
7030: 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70  eful the sync op
7040: 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64  erations are and
7050: 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20  .** only make a 
7060: 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61  difference on Ma
7070: 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65  c OSX for the de
7080: 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64  fault SQLite cod
7090: 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72  e..** (Third-par
70a0: 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ty VFS implement
70b0: 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73  ations might als
70c0: 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  o make the disti
70d0: 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65  nction.** betwee
70e0: 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  n SQLITE_SYNC_NO
70f0: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
7100: 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61  SYNC_FULL, but a
7110: 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72  mong the.** oper
7120: 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61  ating systems na
7130: 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64  tively supported
7140: 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79   by SQLite, only
7150: 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65   Mac OSX.** care
7160: 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66  s about the diff
7170: 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66  erence.).*/.#def
7180: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
7190: 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78  NORMAL        0x
71a0: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
71b0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20  LITE_SYNC_FULL  
71c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a          0x00003.
71d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
71e0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20  YNC_DATAONLY    
71f0: 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a    0x00010../*.**
7200: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
7210: 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c  terface Open Fil
7220: 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41  e Handle.**.** A
7230: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
7240: 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
7250: 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ts an open file 
7260: 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  in the .** [sqli
7270: 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74  te3_vfs | OS int
7280: 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20  erface layer].  
7290: 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e  Individual OS in
72a0: 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65  terface.** imple
72b0: 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a  mentations will.
72c0: 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c  ** want to subcl
72d0: 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20  ass this object 
72e0: 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64  by appending add
72f0: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a  itional fields.*
7300: 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20  * for their own 
7310: 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f  use.  The pMetho
7320: 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f  ds entry is a po
7330: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
7340: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7350: 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  ds] object that 
7360: 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20  defines methods 
7370: 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a  for performing.*
7380: 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  * I/O operations
7390: 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c   on the open fil
73a0: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  e..*/.typedef st
73b0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
73c0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a  e sqlite3_file;.
73d0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
73e0: 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74  ile {.  const st
73f0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
7400: 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64  methods *pMethod
7410: 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  s;  /* Methods f
7420: 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  or an open file 
7430: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
7440: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
7450: 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c  ace File Virtual
7460: 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a   Methods Object.
7470: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65  **.** Every file
7480: 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b   opened by the [
7490: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
74a0: 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61  n] method popula
74b0: 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74  tes an.** [sqlit
74c0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
74d0: 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e  (or, more common
74e0: 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f  ly, a subclass o
74f0: 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
7500: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20  3_file] object) 
7510: 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74  with a pointer t
7520: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
7530: 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a   this object..**
7540: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   This object def
7550: 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73  ines the methods
7560: 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d   used to perform
7570: 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69   various operati
7580: 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74  ons.** against t
7590: 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70  he open file rep
75a0: 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20  resented by the 
75b0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
75c0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  bject..**.** If 
75d0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
75e0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73  .xOpen] method s
75f0: 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ets the sqlite3_
7600: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
7610: 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e  ement .** to a n
7620: 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
7630: 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
7640: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c  3_io_methods.xCl
7650: 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61  ose method.** ma
7660: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65  y be invoked eve
7670: 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n if the [sqlite
7680: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70  3_vfs.xOpen] rep
7690: 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66 61  orted that it fa
76a0: 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e  iled.  The.** on
76b0: 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e  ly way to preven
76c0: 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f  t a call to xClo
76d0: 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66  se following a f
76e0: 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76  ailed [sqlite3_v
76f0: 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20  fs.xOpen].** is 
7700: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
7710: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73  _vfs.xOpen] to s
7720: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
7730: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65  ile.pMethods ele
7740: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e  ment.** to NULL.
7750: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
7760: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79   argument to xSy
7770: 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66  nc may be one of
7780: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f   [SQLITE_SYNC_NO
7790: 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  RMAL] or.** [SQL
77a0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20  ITE_SYNC_FULL]. 
77b0: 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63   The first choic
77c0: 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20  e is the normal 
77d0: 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20  fsync()..** The 
77e0: 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73  second choice is
77f0: 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c   a Mac OS X styl
7800: 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65  e fullsync.  The
7810: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41   [SQLITE_SYNC_DA
7820: 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20  TAONLY].** flag 
7830: 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74  may be ORed in t
7840: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
7850: 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66  only the data of
7860: 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64   the file.** and
7870: 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e   not its inode n
7880: 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65  eeds to be synce
7890: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  d..**.** The int
78a0: 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78  eger values to x
78b0: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
78c0: 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a  ck() are one of.
78d0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
78e0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
78f0: 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
7900: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
7910: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
7920: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
7930: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
7940: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
7950: 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
7960: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
7970: 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  VE]..** </ul>.**
7980: 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73   xLock() increas
7990: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e  es the lock. xUn
79a0: 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73  lock() decreases
79b0: 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68   the lock..** Th
79c0: 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  e xCheckReserved
79d0: 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68  Lock() method ch
79e0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79  ecks whether any
79f0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
7a00: 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20  tion,.** either 
7a10: 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  in this process 
7a20: 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72  or in some other
7a30: 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c   process, is hol
7a40: 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c  ding a RESERVED,
7a50: 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20  .** PENDING, or 
7a60: 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f  EXCLUSIVE lock o
7a70: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20  n the file.  It 
7a80: 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20  returns true.** 
7a90: 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65  if such a lock e
7aa0: 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20  xists and false 
7ab0: 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a  otherwise..**.**
7ac0: 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   The xFileContro
7ad0: 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20  l() method is a 
7ae0: 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63  generic interfac
7af0: 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75  e that allows cu
7b00: 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c  stom.** VFS impl
7b10: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64  ementations to d
7b20: 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20  irectly control 
7b30: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69  an open file usi
7b40: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
7b50: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
7b60: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  )] interface.  T
7b70: 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61  he second "op" a
7b80: 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a  rgument is an.**
7b90: 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e   integer opcode.
7ba0: 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
7bb0: 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69  ment is a generi
7bc0: 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64  c pointer intend
7bd0: 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74  ed to.** point t
7be0: 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68  o a structure th
7bf0: 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61  at may contain a
7c00: 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63  rguments or spac
7c10: 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a  e in which to.**
7c20: 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61   write return va
7c30: 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c  lues.  Potential
7c40: 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43   uses for xFileC
7c50: 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62  ontrol() might b
7c60: 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74  e.** functions t
7c70: 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e  o enable blockin
7c80: 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d  g locks with tim
7c90: 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65  eouts, to change
7ca0: 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20   the.** locking 
7cb0: 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78  strategy (for ex
7cc0: 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74  ample to use dot
7cd0: 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f  -file locks), to
7ce0: 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75   inquire.** abou
7cf0: 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20  t the status of 
7d00: 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72  a lock, or to br
7d10: 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e  eak stale locks.
7d20: 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20    The SQLite.** 
7d30: 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c  core reserves al
7d40: 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74  l opcodes less t
7d50: 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20  han 100 for its 
7d60: 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53  own use..** A [S
7d70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
7d80: 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20  STATE | list of 
7d90: 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68  opcodes] less th
7da0: 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61  an 100 is availa
7db0: 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ble..** Applicat
7dc0: 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65  ions that define
7dd0: 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43   a custom xFileC
7de0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68  ontrol method sh
7df0: 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73  ould use opcodes
7e00: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e  .** greater than
7e10: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f   100 to avoid co
7e20: 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d  nflicts.  VFS im
7e30: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
7e40: 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
7e50: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
7e60: 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f   for file contro
7e70: 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74  l opcodes that t
7e80: 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65  hey do not.** re
7e90: 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54  cognize..**.** T
7ea0: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29  he xSectorSize()
7eb0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
7ec0: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  the sector size 
7ed0: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65  of the.** device
7ee0: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20   that underlies 
7ef0: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73  the file.  The s
7f00: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68  ector size is th
7f10: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69  e.** minimum wri
7f20: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70  te that can be p
7f30: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74  erformed without
7f40: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f   disturbing.** o
7f50: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68  ther bytes in th
7f60: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65  e file.  The xDe
7f70: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
7f80: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ics().** method 
7f90: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65  returns a bit ve
7fa0: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20  ctor describing 
7fb0: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65  behaviors of the
7fc0: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64  .** underlying d
7fd0: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  evice:.**.** <ul
7fe0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
7ff0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a  E_IOCAP_ATOMIC].
8000: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8010: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d  IOCAP_ATOMIC512]
8020: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8030: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d  _IOCAP_ATOMIC1K]
8040: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8050: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d  _IOCAP_ATOMIC2K]
8060: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8070: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d  _IOCAP_ATOMIC4K]
8080: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8090: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d  _IOCAP_ATOMIC8K]
80a0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
80b0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
80c0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
80d0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
80e0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
80f0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
8100: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
8110: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
8120: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  PPEND].** <li> [
8130: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
8140: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  UENTIAL].** </ul
8150: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
8160: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
8170: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
8180: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
8190: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
81a0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
81b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
81c0: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
81d0: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
81e0: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
81f0: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
8200: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
8210: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
8220: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
8230: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
8240: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
8250: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
8260: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
8270: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
8280: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
8290: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
82a0: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
82b0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
82c0: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
82d0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
82e0: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
82f0: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
8300: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
8310: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8320: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
8330: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
8340: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
8350: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
8360: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
8370: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
8380: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
8390: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20  *.** If xRead() 
83a0: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49  returns SQLITE_I
83b0: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
83c0: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c  it must also fil
83d0: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65  l.** in the unre
83e0: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74  ad portions of t
83f0: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a  he buffer with z
8400: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61  eros.  A VFS tha
8410: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65  t.** fails to ze
8420: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
8430: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74  ads might seem t
8440: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72  o work.  However
8450: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20  ,.** failure to 
8460: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
8470: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74  reads will event
8480: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a  ually lead to.**
8490: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   database corrup
84a0: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
84b0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
84c0: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  io_methods sqlit
84d0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73  e3_io_methods;.s
84e0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
84f0: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74  _methods {.  int
8500: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
8510: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
8520: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
8530: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65   (*xRead)(sqlite
8540: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20  3_file*, void*, 
8550: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
8560: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
8570: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28    int (*xWrite)(
8580: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63  sqlite3_file*, c
8590: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
85a0: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
85b0: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
85c0: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73  t (*xTruncate)(s
85d0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
85e0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65  lite3_int64 size
85f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
8600: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8610: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69   int flags);.  i
8620: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28  nt (*xFileSize)(
8630: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8640: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53  qlite3_int64 *pS
8650: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c  ize);.  int (*xL
8660: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
8670: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
8680: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74  (*xUnlock)(sqlit
8690: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
86a0: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65    int (*xCheckRe
86b0: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69  servedLock)(sqli
86c0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a  te3_file*, int *
86d0: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
86e0: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28  (*xFileControl)(
86f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8700: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72  nt op, void *pAr
8710: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63  g);.  int (*xSec
8720: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33  torSize)(sqlite3
8730: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
8740: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65  *xDeviceCharacte
8750: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33  ristics)(sqlite3
8760: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65  _file*);.  /* Me
8770: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
8780: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
8790: 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 1 */.  int (*x
87a0: 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f  ShmMap)(sqlite3_
87b0: 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20  file*, int iPg, 
87c0: 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76  int pgsz, int, v
87d0: 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b  oid volatile**);
87e0: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63  .  int (*xShmLoc
87f0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
8800: 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e  , int offset, in
8810: 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  t n, int flags);
8820: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61  .  void (*xShmBa
8830: 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66  rrier)(sqlite3_f
8840: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
8850: 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65  ShmUnmap)(sqlite
8860: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c  3_file*, int del
8870: 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d  eteFlag);.  /* M
8880: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8890: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
88a0: 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 2 */.  int (*
88b0: 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f  xFetch)(sqlite3_
88c0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
88d0: 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20  nt64 iOfst, int 
88e0: 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29  iAmt, void **pp)
88f0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74  ;.  int (*xUnfet
8900: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ch)(sqlite3_file
8910: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
8920: 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29   iOfst, void *p)
8930: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8940: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8950: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a  or version 3 */.
8960: 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20    /* Additional 
8970: 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61  methods may be a
8980: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
8990: 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f  eleases */.};../
89a0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
89b0: 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e  tandard File Con
89c0: 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a  trol Opcodes.**.
89d0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
89e0: 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f   constants are o
89f0: 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78  pcodes for the x
8a00: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
8a10: 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  od.** of the [sq
8a20: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
8a30: 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72  ] object and for
8a40: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
8a50: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a  le_control()].**
8a60: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
8a70: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
8a80: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f  NTL_LOCKSTATE] o
8a90: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f  pcode is used fo
8aa0: 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68  r debugging.  Th
8ab0: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75  is.** opcode cau
8ac0: 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  ses the xFileCon
8ad0: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77  trol method to w
8ae0: 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74  rite the current
8af0: 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65   state of.** the
8b00: 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53   lock (one of [S
8b10: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d  QLITE_LOCK_NONE]
8b20: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  , [SQLITE_LOCK_S
8b30: 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  HARED],.** [SQLI
8b40: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
8b50: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
8b60: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51  PENDING], or [SQ
8b70: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
8b80: 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e  IVE]).** into an
8b90: 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68   integer that th
8ba0: 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20  e pArg argument 
8bb0: 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20  points to. This 
8bc0: 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73  capability.** is
8bd0: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
8be0: 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65  ting and only ne
8bf0: 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72  eds to be suppor
8c00: 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ted when SQLITE_
8c10: 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e  TEST.** is defin
8c20: 65 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  ed..** <ul>.** <
8c30: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
8c40: 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a  L_SIZE_HINT]].**
8c50: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
8c60: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70  TL_SIZE_HINT] op
8c70: 63 6f 64 65 20 69 73 20 75 73 65 64 20 62 79 20  code is used by 
8c80: 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74  SQLite to give t
8c90: 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20  he VFS.** layer 
8ca0: 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61  a hint of how la
8cb0: 72 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  rge the database
8cc0: 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20   file will grow 
8cd0: 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68 65  to be during the
8ce0: 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e  .** current tran
8cf0: 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68  saction.  This h
8d00: 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61  int is not guara
8d10: 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63 63 75  nteed to be accu
8d20: 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69  rate but it.** i
8d30: 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20  s often close.  
8d40: 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56  The underlying V
8d50: 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20  FS might choose 
8d60: 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64  to preallocate d
8d70: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
8d80: 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74  space based on t
8d90: 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65  his hint in orde
8da0: 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73  r to help writes
8db0: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
8dc0: 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73  .** file run fas
8dd0: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ter..**.** <li>[
8de0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48  [SQLITE_FCNTL_CH
8df0: 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68  UNK_SIZE]].** Th
8e00: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8e10: 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f  CHUNK_SIZE] opco
8e20: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65  de is used to re
8e30: 71 75 65 73 74 20 74 68 61 74 20 74 68 65 20 56  quest that the V
8e40: 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e  FS.** extends an
8e50: 64 20 74 72 75 6e 63 61 74 65 73 20 74 68 65 20  d truncates the 
8e60: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e  database file in
8e70: 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a   chunks of a siz
8e80: 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  e specified.** b
8e90: 79 20 74 68 65 20 75 73 65 72 2e 20 54 68 65 20  y the user. The 
8ea0: 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
8eb0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  to [sqlite3_file
8ec0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75  _control()] shou
8ed0: 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20  ld .** point to 
8ee0: 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70 65  an integer (type
8ef0: 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67   int) containing
8f00: 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73   the new chunk-s
8f10: 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f  ize to use.** fo
8f20: 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20  r the nominated 
8f30: 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61  database. Alloca
8f40: 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 66 69  ting database fi
8f50: 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67  le space in larg
8f60: 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79  e.** chunks (say
8f70: 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c   1MB at a time),
8f80: 20 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c 65   may reduce file
8f90: 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74  -system fragment
8fa0: 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70  ation and.** imp
8fb0: 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  rove performance
8fc0: 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73   on some systems
8fd0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
8fe0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
8ff0: 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65  POINTER]].** The
9000: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46   [SQLITE_FCNTL_F
9010: 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63  ILE_POINTER] opc
9020: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f  ode is used to o
9030: 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a  btain a pointer.
9040: 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
9050: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
9060: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
9070: 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74  a particular dat
9080: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
9090: 69 6f 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73  ion.  See the [s
90a0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
90b0: 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61  rol()] documenta
90c0: 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69  tion for.** addi
90d0: 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
90e0: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  on..**.** <li>[[
90f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
9100: 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 5e  C_OMITTED]].** ^
9110: 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  (The [SQLITE_FCN
9120: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d  TL_SYNC_OMITTED]
9130: 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72   opcode is gener
9140: 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  ated internally 
9150: 62 79 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64  by.** SQLite and
9160: 20 73 65 6e 74 20 74 6f 20 61 6c 6c 20 56 46 53   sent to all VFS
9170: 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 61  es in place of a
9180: 20 63 61 6c 6c 20 74 6f 20 74 68 65 20 78 53 79   call to the xSy
9190: 6e 63 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 68 65  nc method.** whe
91a0: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
91b0: 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 73 20 5b 50  onnection has [P
91c0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
91d0: 73 5d 20 73 65 74 20 74 6f 20 4f 46 46 2e 29 5e  s] set to OFF.)^
91e0: 0a 2a 2a 20 53 6f 6d 65 20 73 70 65 63 69 61 6c  .** Some special
91f0: 69 7a 65 64 20 56 46 53 65 73 20 6e 65 65 64 20  ized VFSes need 
9200: 74 68 69 73 20 73 69 67 6e 61 6c 20 69 6e 20 6f  this signal in o
9210: 72 64 65 72 20 74 6f 20 6f 70 65 72 61 74 65 20  rder to operate 
9220: 63 6f 72 72 65 63 74 6c 79 0a 2a 2a 20 77 68 65  correctly.** whe
9230: 6e 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  n [PRAGMA synchr
9240: 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73  onous | PRAGMA s
9250: 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20  ynchronous=OFF] 
9260: 69 73 20 73 65 74 2c 20 62 75 74 20 6d 6f 73 74  is set, but most
9270: 20 0a 2a 2a 20 56 46 53 65 73 20 64 6f 20 6e 6f   .** VFSes do no
9280: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  t need this sign
9290: 61 6c 20 61 6e 64 20 73 68 6f 75 6c 64 20 73 69  al and should si
92a0: 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68  lently ignore th
92b0: 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 20 41 70  is opcode..** Ap
92c0: 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
92d0: 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69  d not call [sqli
92e0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
92f0: 28 29 5d 20 77 69 74 68 20 74 68 69 73 0a 2a 2a  ()] with this.**
9300: 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67   opcode as doing
9310: 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20   so may disrupt 
9320: 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66  the operation of
9330: 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64   the specialized
9340: 20 56 46 53 65 73 0a 2a 2a 20 74 68 61 74 20 64   VFSes.** that d
9350: 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a  o require it.  .
9360: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9370: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
9380: 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68  V_RETRY]].** ^Th
9390: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
93a0: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20  WIN32_AV_RETRY] 
93b0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
93c0: 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f  o configure auto
93d0: 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63  matic.** retry c
93e0: 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76  ounts and interv
93f0: 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20  als for certain 
9400: 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69  disk I/O operati
9410: 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77  ons for the.** w
9420: 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20  indows [VFS] in 
9430: 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65  order to provide
9440: 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74   robustness in t
9450: 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a  he presence of.*
9460: 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f  * anti-virus pro
9470: 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75  grams.  By defau
9480: 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20  lt, the windows 
9490: 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66  VFS will retry f
94a0: 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c  ile read,.** fil
94b0: 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c  e write, and fil
94c0: 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69  e delete operati
94d0: 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d  ons up to 10 tim
94e0: 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79  es, with a delay
94f0: 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73  .** of 25 millis
9500: 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68  econds before th
9510: 65 20 66 69 72 73 74 20 72 65 74 72 79 20 61 6e  e first retry an
9520: 64 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 79  d with the delay
9530: 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62   increasing.** b
9540: 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20  y an additional 
9550: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
9560: 77 69 74 68 20 65 61 63 68 20 73 75 62 73 65 71  with each subseq
9570: 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69  uent retry.  Thi
9580: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f  s.** opcode allo
9590: 77 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c  ws these two val
95a0: 75 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20  ues (10 retries 
95b0: 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f  and 25 milliseco
95c0: 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a  nds of delay).**
95d0: 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e   to be adjusted.
95e0: 20 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65    The values are
95f0: 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c   changed for all
9600: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
9610: 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20  tions.** within 
9620: 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73  the same process
9630: 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
9640: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
9650: 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a  an array of two.
9660: 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72  ** integers wher
9670: 65 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65  e the first inte
9680: 67 65 72 20 69 20 74 68 65 20 6e 65 77 20 72 65  ger i the new re
9690: 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68  try count and th
96a0: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65  e second.** inte
96b0: 67 65 72 20 69 73 20 74 68 65 20 64 65 6c 61 79  ger is the delay
96c0: 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 6e 74  .  If either int
96d0: 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 76 65  eger is negative
96e0: 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 74 69  , then the setti
96f0: 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  ng.** is not cha
9700: 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 61 64  nged but instead
9710: 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
9720: 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e 67   of that setting
9730: 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69   is written.** i
9740: 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e  nto the array en
9750: 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68  try, allowing th
9760: 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 79 20  e current retry 
9770: 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a  settings to be.*
9780: 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20  * interrogated. 
9790: 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72   The zDbName par
97a0: 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65  ameter is ignore
97b0: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
97c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
97d0: 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68  IST_WAL]].** ^Th
97e0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
97f0: 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63  PERSIST_WAL] opc
9800: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73  ode is used to s
9810: 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a  et or query the.
9820: 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57  ** persistent [W
9830: 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61 64  AL | Write Ahead
9840: 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20   Log] setting.  
9850: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
9860: 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69  auxiliary.** wri
9870: 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64  te ahead log and
9880: 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66   shared memory f
9890: 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74 72  iles used for tr
98a0: 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f  ansaction contro
98b0: 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74  l.** are automat
98c0: 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77  ically deleted w
98d0: 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63  hen the latest c
98e0: 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65  onnection to the
98f0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f   database.** clo
9900: 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65  ses.  Setting pe
9910: 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64  rsistent WAL mod
9920: 65 20 63 61 75 73 65 73 20 74 68 6f 73 65 20 66  e causes those f
9930: 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74 20  iles to persist 
9940: 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20  after.** close. 
9950: 20 50 65 72 73 69 73 74 69 6e 67 20 74 68 65 20   Persisting the 
9960: 66 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20  files is useful 
9970: 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65  when other proce
9980: 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  sses that do not
9990: 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20 70  .** have write p
99a0: 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65  ermission on the
99b0: 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61   directory conta
99c0: 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  ining the databa
99d0: 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20  se file want.** 
99e0: 74 6f 20 72 65 61 64 20 74 68 65 20 64 61 74 61  to read the data
99f0: 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68  base file, as th
9a00: 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64  e WAL and shared
9a10: 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75   memory files mu
9a20: 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f  st exist.** in o
9a30: 72 64 65 72 20 66 6f 72 20 74 68 65 20 64 61 74  rder for the dat
9a40: 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 61 64  abase to be read
9a50: 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74  able.  The fourt
9a60: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  h parameter to.*
9a70: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
9a80: 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74  control()] for t
9a90: 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c  his opcode shoul
9aa0: 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  d be a pointer t
9ab0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  o an integer..**
9ac0: 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73   That integer is
9ad0: 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65   0 to disable pe
9ae0: 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64  rsistent WAL mod
9af0: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65  e or 1 to enable
9b00: 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57   persistent.** W
9b10: 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  AL mode.  If the
9b20: 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20   integer is -1, 
9b30: 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77  then it is overw
9b40: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20  ritten with the 
9b50: 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70  current.** WAL p
9b60: 65 72 73 69 73 74 65 6e 63 65 20 73 65 74 74 69  ersistence setti
9b70: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ng..**.** <li>[[
9b80: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
9b90: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
9ba0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
9bb0: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
9bc0: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70  FE_OVERWRITE] op
9bd0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
9be0: 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65  set or query the
9bf0: 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22  .** persistent "
9c00: 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72  powersafe-overwr
9c10: 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73  ite" or "PSOW" s
9c20: 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f  etting.  The PSO
9c30: 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74  W setting.** det
9c40: 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c  ermines the [SQL
9c50: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53  ITE_IOCAP_POWERS
9c60: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62  AFE_OVERWRITE] b
9c70: 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65  it of the.** xDe
9c80: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
9c90: 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65  ics methods. The
9ca0: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
9cb0: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
9cc0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
9cd0: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65   for this opcode
9ce0: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69   should be a poi
9cf0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
9d00: 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65  er..** That inte
9d10: 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61  ger is 0 to disa
9d20: 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20  ble zero-damage 
9d30: 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61  mode or 1 to ena
9d40: 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a  ble zero-damage.
9d50: 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ** mode.  If the
9d60: 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20   integer is -1, 
9d70: 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77  then it is overw
9d80: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20  ritten with the 
9d90: 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d  current.** zero-
9da0: 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74  damage mode sett
9db0: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ing..**.** <li>[
9dc0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56  [SQLITE_FCNTL_OV
9dd0: 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68  ERWRITE]].** ^Th
9de0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9df0: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64  OVERWRITE] opcod
9e00: 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20  e is invoked by 
9e10: 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65  SQLite after ope
9e20: 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20  ning.** a write 
9e30: 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69  transaction to i
9e40: 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e  ndicate that, un
9e50: 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65  less it is rolle
9e60: 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a  d back for some.
9e70: 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65  ** reason, the e
9e80: 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 20 66  ntire database f
9e90: 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72  ile will be over
9ea0: 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 63  written by the c
9eb0: 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73  urrent .** trans
9ec0: 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20  action. This is 
9ed0: 75 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f  used by VACUUM o
9ee0: 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
9ef0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9f00: 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a  NTL_VFSNAME]].**
9f10: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
9f20: 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63  NTL_VFSNAME] opc
9f30: 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ode can be used 
9f40: 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61  to obtain the na
9f50: 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56  mes of.** all [V
9f60: 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53  FSes] in the VFS
9f70: 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d   stack.  The nam
9f80: 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46  es are of all VF
9f90: 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a  S shims and the.
9fa0: 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d  ** final bottom-
9fb0: 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 77 72  level VFS are wr
9fc0: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
9fd0: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
9fe0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
9ff0: 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72  loc()] and the r
a000: 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20  esult is stored 
a010: 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61 72  in the char* var
a020: 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68  iable.** that th
a030: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
a040: 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66  er of [sqlite3_f
a050: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70  ile_control()] p
a060: 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65  oints to..** The
a070: 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f   caller is respo
a080: 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69  nsible for freei
a090: 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68  ng the memory wh
a0a0: 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74  en done.  As wit
a0b0: 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f  h.** all file-co
a0c0: 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74  ntrol actions, t
a0d0: 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61  here is no guara
a0e0: 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 20 77  ntee that this w
a0f0: 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20  ill actually.** 
a100: 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61  do anything.  Ca
a110: 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69  llers should ini
a120: 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72  tialize the char
a130: 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20  * variable to a 
a140: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
a150: 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 69 6c  in case this fil
a160: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74  e-control is not
a170: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54   implemented.  T
a180: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
a190: 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20  .** is intended 
a1a0: 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75  for diagnostic u
a1b0: 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c  se only..**.** <
a1c0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
a1d0: 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57  L_PRAGMA]].** ^W
a1e0: 68 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d  henever a [PRAGM
a1f0: 41 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  A] statement is 
a200: 70 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49  parsed, an [SQLI
a210: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a220: 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f   .** file contro
a230: 6c 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65  l is sent to the
a240: 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   open [sqlite3_f
a250: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72  ile] object corr
a260: 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20  esponding.** to 
a270: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
a280: 65 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70  e to which the p
a290: 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20  ragma statement 
a2a0: 72 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67  refers. ^The arg
a2b0: 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20  ument.** to the 
a2c0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
a2d0: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
a2e0: 6f 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ol is an array o
a2f0: 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f  f.** pointers to
a300: 20 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a   strings (char**
a310: 29 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73  ) in which the s
a320: 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66  econd element of
a330: 20 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73   the array.** is
a340: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
a350: 20 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20   pragma and the 
a360: 74 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73  third element is
a370: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
a380: 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f   the.** pragma o
a390: 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72  r NULL if the pr
a3a0: 61 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75  agma has no argu
a3b0: 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64  ment.  ^The hand
a3c0: 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53  ler for an.** [S
a3d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
a3e0: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
a3f0: 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20   can optionally 
a400: 6d 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65  make the first e
a410: 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65  lement.** of the
a420: 20 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74   char** argument
a430: 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69   point to a stri
a440: 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ng obtained from
a450: 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   [sqlite3_mprint
a460: 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65  f()].** or the e
a470: 71 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68  quivalent and th
a480: 61 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  at string will b
a490: 65 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74  ecome the result
a4a0: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f   of the pragma o
a4b0: 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d  r.** the error m
a4c0: 65 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72  essage if the pr
a4d0: 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20  agma fails. ^If 
a4e0: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  the.** [SQLITE_F
a4f0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
a500: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
a510: 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  s [SQLITE_NOTFOU
a520: 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c  ND], then normal
a530: 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72   .** [PRAGMA] pr
a540: 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75  ocessing continu
a550: 65 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51  es.  ^If the [SQ
a560: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
a570: 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72  A].** file contr
a580: 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ol returns [SQLI
a590: 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65  TE_OK], then the
a5a0: 20 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20   parser assumes 
a5b0: 74 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20  that the.** VFS 
a5c0: 68 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20  has handled the 
a5d0: 50 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e  PRAGMA itself an
a5e0: 64 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e  d the parser gen
a5f0: 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a  erates a no-op.*
a600: 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
a610: 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 5b  ment.  ^If the [
a620: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
a630: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
a640: 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  l returns.** any
a650: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68   result code oth
a660: 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
a670: 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e  OK] or [SQLITE_N
a680: 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d  OTFOUND], that m
a690: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65  eans.** that the
a6a0: 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64   VFS encountered
a6b0: 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20   an error while 
a6c0: 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52  handling the [PR
a6d0: 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a  AGMA] and the.**
a6e0: 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20   compilation of 
a6f0: 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73  the PRAGMA fails
a700: 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
a710: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
a720: 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66  NTL_PRAGMA].** f
a730: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75  ile control occu
a740: 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e  rs at the beginn
a750: 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74  ing of pragma st
a760: 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73  atement analysis
a770: 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73   and so.** it is
a780: 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64   able to overrid
a790: 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47  e built-in [PRAG
a7a0: 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  MA] statements..
a7b0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a7c0: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
a7d0: 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  DLER]].** ^The [
a7e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
a7f0: 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c  YHANDLER].** fil
a800: 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65  e-control may be
a810: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
a820: 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  te on the databa
a830: 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a  se file handle.*
a840: 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20  * shortly after 
a850: 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20  it is opened in 
a860: 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65  order to provide
a870: 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69   a custom VFS wi
a880: 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  th access.** to 
a890: 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  the connections 
a8a0: 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c  busy-handler cal
a8b0: 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d  lback. The argum
a8c0: 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20 28  ent is of type (
a8d0: 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e  void **).** - an
a8e0: 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76   array of two (v
a8f0: 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54  oid *) values. T
a900: 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a  he first (void *
a910: 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74  ) actually point
a920: 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69  s.** to a functi
a930: 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20  on of type (int 
a940: 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e  (*)(void *)). In
a950: 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65   order to invoke
a960: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   the connections
a970: 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72  .** busy-handler
a980: 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  , this function 
a990: 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65  should be invoke
a9a0: 64 20 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e  d with the secon
a9b0: 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a  d (void *) in.**
a9c0: 20 74 68 65 20 61 72 72 61 79 20 61 73 20 74 68   the array as th
a9d0: 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e  e only argument.
a9e0: 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e   If it returns n
a9f0: 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68  on-zero, then th
aa00: 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73  e operation.** s
aa10: 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65 64  hould be retried
aa20: 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20  . If it returns 
aa30: 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d  zero, the custom
aa40: 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e   VFS should aban
aa50: 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65  don the.** curre
aa60: 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a  nt operation..**
aa70: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
aa80: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
aa90: 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63  AME]].** ^Applic
aaa0: 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65  ation can invoke
aab0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
aac0: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d  TL_TEMPFILENAME]
aad0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a   file-control.**
aae0: 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20   to have SQLite 
aaf0: 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65  generate a.** te
ab00: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65  mporary filename
ab10: 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
ab20: 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69  algorithm that i
ab30: 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65  s followed to ge
ab40: 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72  nerate.** tempor
ab50: 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f  ary filenames fo
ab60: 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e  r TEMP tables an
ab70: 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c  d other internal
ab80: 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61   uses.  The.** a
ab90: 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
aba0: 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68  e a char** which
abb0: 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20   will be filled 
abc0: 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d  with the filenam
abd0: 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74  e.** written int
abe0: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
abf0: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
ac00: 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20  malloc()].  The 
ac10: 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a  caller should.**
ac20: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
ac30: 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20  _free()] on the 
ac40: 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20  result to avoid 
ac50: 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a  a memory leak..*
ac60: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
ac70: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
ac80: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
ac90: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
aca0: 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  ZE] file control
acb0: 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 65 72   is used to quer
acc0: 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a 20  y or set the.** 
acd0: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
ace0: 66 20 62 79 74 65 73 20 74 68 61 74 20 77 69 6c  f bytes that wil
acf0: 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d 65  l be used for me
ad00: 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e  mory-mapped I/O.
ad10: 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
ad20: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
ad30: 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70 65   a value of type
ad40: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 74   sqlite3_int64 t
ad50: 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76  hat.** is an adv
ad60: 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75  isory maximum nu
ad70: 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
ad80: 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d   the file to mem
ad90: 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a  ory map.  The.**
ada0: 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 72   pointer is over
adb0: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
adc0: 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 65   old value.  The
add0: 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 68   limit is not ch
ade0: 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 20  anged if.** the 
adf0: 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79  value originally
ae00: 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 6e   pointed to is n
ae10: 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f 20  egative, and so 
ae20: 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d 69  the current limi
ae30: 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 65  t .** can be que
ae40: 72 69 65 64 20 62 79 20 70 61 73 73 69 6e 67 20  ried by passing 
ae50: 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  in a pointer to 
ae60: 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
ae70: 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65  r.  This.** file
ae80: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64  -control is used
ae90: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69   internally to i
aea0: 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41  mplement [PRAGMA
aeb0: 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a   mmap_size]..**.
aec0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
aed0: 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a  FCNTL_TRACE]].**
aee0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
aef0: 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 63  TL_TRACE] file c
af00: 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 20  ontrol provides 
af10: 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61  advisory informa
af20: 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56  tion.** to the V
af30: 46 53 20 61 62 6f 75 74 20 77 68 61 74 20 74 68  FS about what th
af40: 65 20 68 69 67 68 65 72 20 6c 61 79 65 72 73 20  e higher layers 
af50: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 73 74  of the SQLite st
af60: 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a  ack are doing..*
af70: 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74  * This file cont
af80: 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20 73  rol is used by s
af90: 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69 74 79  ome VFS activity
afa0: 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d   tracing [shims]
afb0: 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
afc0: 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t is a zero-term
afd0: 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20 20  inated string.  
afe0: 48 69 67 68 65 72 20 6c 61 79 65 72 73 20 69 6e  Higher layers in
aff0: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73   the.** SQLite s
b000: 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 74  tack may generat
b010: 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 74  e instances of t
b020: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
b030: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49   if.** the [SQLI
b040: 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41  TE_USE_FCNTL_TRA
b050: 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  CE] compile-time
b060: 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c   option is enabl
b070: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a  ed..**.** </ul>.
b080: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
b090: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
b0a0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
b0b0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
b0c0: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
b0d0: 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20 32  LE             2
b0e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b0f0: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
b100: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a  E             3.
b110: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
b120: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20  AST_ERRNO       
b130: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23               4.#
b140: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b150: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20  NTL_SIZE_HINT   
b160: 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
b170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b180: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20  TL_CHUNK_SIZE   
b190: 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
b1a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b1b0: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20  L_FILE_POINTER  
b1c0: 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
b1d0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b1e0: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20  _SYNC_OMITTED   
b1f0: 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69           8.#defi
b200: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b210: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20  WIN32_AV_RETRY  
b220: 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e          9.#defin
b230: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
b240: 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20  ERSIST_WAL      
b250: 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65        10.#define
b260: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56   SQLITE_FCNTL_OV
b270: 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20  ERWRITE         
b280: 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20       11.#define 
b290: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
b2a0: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20  NAME            
b2b0: 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53      12.#define S
b2c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
b2d0: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
b2e0: 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51     13.#define SQ
b2f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
b300: 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
b310: 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c    14.#define SQL
b320: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
b330: 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 20  NDLER           
b340: 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   15.#define SQLI
b350: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c  TE_FCNTL_TEMPFIL
b360: 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20  ENAME           
b370: 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  16.#define SQLIT
b380: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
b390: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31  E              1
b3a0: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
b3b0: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20  _FCNTL_TRACE    
b3c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39                19
b3d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
b3e0: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a  : Mutex Handle.*
b3f0: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d  *.** The mutex m
b400: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c  odule within SQL
b410: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c  ite defines [sql
b420: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62  ite3_mutex] to b
b430: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74  e an.** abstract
b440: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65   type for a mute
b450: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53  x object.  The S
b460: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72  QLite core never
b470: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65   looks.** at the
b480: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
b490: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b  entation of an [
b4a0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20  sqlite3_mutex]. 
b4b0: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c   It only.** deal
b4c0: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20  s with pointers 
b4d0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
b4e0: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a  mutex] object..*
b4f0: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65  *.** Mutexes are
b500: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
b510: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
b520: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  loc()]..*/.typed
b530: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
b540: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f  3_mutex sqlite3_
b550: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  mutex;../*.** CA
b560: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
b570: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  face Object.**.*
b580: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
b590: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
b5a0: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
b5b0: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
b5c0: 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c  tween.** the SQL
b5d0: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65  ite core and the
b5e0: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
b5f0: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54  ating system.  T
b600: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74  he "vfs".** in t
b610: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f  he name of the o
b620: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72  bject stands for
b630: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73   "virtual file s
b640: 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20  ystem".  See.** 
b650: 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64  the [VFS | VFS d
b660: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
b670: 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d  r further inform
b680: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
b690: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56   value of the iV
b6a0: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20  ersion field is 
b6b0: 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20  initially 1 but 
b6c0: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e  may be larger in
b6d0: 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69  .** future versi
b6e0: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ons of SQLite.  
b6f0: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  Additional field
b700: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
b710: 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a  d to this.** obj
b720: 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65  ect when the iVe
b730: 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69  rsion value is i
b740: 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20  ncreased.  Note 
b750: 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75  that the structu
b760: 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  re.** of the sql
b770: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
b780: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74  changes in the t
b790: 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65  ransaction betwe
b7a0: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  en.** SQLite ver
b7b0: 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33  sion 3.5.9 and 3
b7c0: 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65  .6.0 and yet the
b7d0: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
b7e0: 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66  was not.** modif
b7f0: 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ied..**.** The s
b800: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73  zOsFile field is
b810: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
b820: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c   subclassed [sql
b830: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74  ite3_file].** st
b840: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20  ructure used by 
b850: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74  this VFS.  mxPat
b860: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78  hname is the max
b870: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a  imum length of.*
b880: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20  * a pathname in 
b890: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20  this VFS..**.** 
b8a0: 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74  Registered sqlit
b8b0: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61  e3_vfs objects a
b8c0: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e  re kept on a lin
b8d0: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20  ked list formed 
b8e0: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20  by.** the pNext 
b8f0: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73  pointer.  The [s
b900: 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
b910: 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ter()].** and [s
b920: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
b930: 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61  ister()] interfa
b940: 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20  ces manage this 
b950: 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72  list.** in a thr
b960: 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54  ead-safe way.  T
b970: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
b980: 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63  find()] interfac
b990: 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68  e.** searches th
b9a0: 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72  e list.  Neither
b9b0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
b9c0: 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46   code nor the VF
b9d0: 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  S.** implementat
b9e0: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74  ion should use t
b9f0: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
ba00: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78  ..**.** The pNex
ba10: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f  t field is the o
ba20: 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65  nly field in the
ba30: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
ba40: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53  structure that S
ba50: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20  QLite will ever 
ba60: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20  modify.  SQLite 
ba70: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73  will only access
ba80: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  .** or modify th
ba90: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68  is field while h
baa0: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75  olding a particu
bab0: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78  lar static mutex
bac0: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
bad0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
bae0: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e  r modify anythin
baf0: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c  g within the sql
bb00: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65  ite3_vfs.** obje
bb10: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65  ct once the obje
bb20: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69  ct has been regi
bb30: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  stered..**.** Th
bb40: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f  e zName field ho
bb50: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lds the name of 
bb60: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20  the VFS module. 
bb70: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a   The name must.*
bb80: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f  * be unique acro
bb90: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c  ss all VFS modul
bba0: 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  es..**.** [[sqli
bbb0: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a  te3_vfs.xOpen]].
bbc0: 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61  ** ^SQLite guara
bbd0: 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a  ntees that the z
bbe0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
bbf0: 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69  er to xOpen.** i
bc00: 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  s either a NULL 
bc10: 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e  pointer or strin
bc20: 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  g obtained.** fr
bc30: 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  om xFullPathname
bc40: 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f  () with an optio
bc50: 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64  nal suffix added
bc60: 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69  ..** ^If a suffi
bc70: 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68  x is added to th
bc80: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
bc90: 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a  meter, it will.*
bca0: 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73  * consist of a s
bcb0: 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63  ingle "-" charac
bcc0: 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  ter followed by 
bcd0: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20  no more than.** 
bce0: 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  11 alphanumeric 
bcf0: 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61  and/or "-" chara
bd00: 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74  cters..** ^SQLit
bd10: 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e  e further guaran
bd20: 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  tees that.** the
bd30: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
bd40: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e  valid and unchan
bd50: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65  ged until xClose
bd60: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e  () is.** called.
bd70: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
bd80: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
bd90: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  e,.** the [sqlit
bda0: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66  e3_file] can saf
bdb0: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e  ely store a poin
bdc0: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69  ter to the.** fi
bdd0: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65  lename if it nee
bde0: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74  ds to remember t
bdf0: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20  he filename for 
be00: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20  some reason..** 
be10: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  If the zFilename
be20: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
be30: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  pen is a NULL po
be40: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e  inter then xOpen
be50: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20  .** must invent 
be60: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72  its own temporar
be70: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66  y name for the f
be80: 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20  ile.  ^Whenever 
be90: 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d  the .** xFilenam
bea0: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e  e parameter is N
beb0: 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f  ULL it will also
bec0: 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
bed0: 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70  t the.** flags p
bee0: 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e  arameter will in
bef0: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
bf00: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
bf10: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  ]..**.** The fla
bf20: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
bf30: 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20  Open() includes 
bf40: 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a  all bits set in.
bf50: 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  ** the flags arg
bf60: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
bf70: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f  3_open_v2()].  O
bf80: 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r if [sqlite3_op
bf90: 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  en()].** or [sql
bfa0: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69  ite3_open16()] i
bfb0: 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61  s used, then fla
bfc0: 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c  gs includes at l
bfd0: 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  east.** [SQLITE_
bfe0: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
bff0: 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
c000: 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78  REATE]. .** If x
c010: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66  Open() opens a f
c020: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68  ile read-only th
c030: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74  en it sets *pOut
c040: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c  Flags to.** incl
c050: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
c060: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68  _READONLY].  Oth
c070: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74  er bits in *pOut
c080: 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74  Flags may be set
c090: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65  ..**.** ^(SQLite
c0a0: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f   will also add o
c0b0: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
c0c0: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
c0d0: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c   xOpen().** call
c0e0: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
c0f0: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20  he object being 
c100: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  opened:.**.** <u
c110: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  l>.** <li>  [SQL
c120: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
c130: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
c140: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
c150: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
c160: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
c170: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
c180: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
c190: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
c1a0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
c1b0: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20  RANSIENT_DB].** 
c1c0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
c1d0: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a  EN_SUBJOURNAL].*
c1e0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
c1f0: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
c200: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
c210: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a  QLITE_OPEN_WAL].
c220: 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
c230: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d   The file I/O im
c240: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e  plementation can
c250: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20   use the object 
c260: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a  type flags to.**
c270: 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20   change the way 
c280: 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69  it deals with fi
c290: 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  les.  For exampl
c2a0: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
c2b0: 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e  n.** that does n
c2c0: 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72  ot care about cr
c2d0: 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20  ash recovery or 
c2e0: 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d  rollback might m
c2f0: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20  ake.** the open 
c300: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c  of a journal fil
c310: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74  e a no-op.  Writ
c320: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e  es to this journ
c330: 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f  al would.** also
c340: 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20   be no-ops, and 
c350: 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72  any attempt to r
c360: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20  ead the journal 
c370: 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20  would return.** 
c380: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f  SQLITE_IOERR.  O
c390: 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  r the implementa
c3a0: 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67  tion might recog
c3b0: 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61  nize that a data
c3c0: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c  base.** file wil
c3d0: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d  l be doing page-
c3e0: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72  aligned sector r
c3f0: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20  eads and writes 
c400: 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f  in a random.** o
c410: 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20  rder and set up 
c420: 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65  its I/O subsyste
c430: 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a  m accordingly..*
c440: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68  *.** SQLite migh
c450: 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  t also add one o
c460: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
c470: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
c480: 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  en method:.**.**
c490: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
c4a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
c4b0: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69  EONCLOSE].** <li
c4c0: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  > [SQLITE_OPEN_E
c4d0: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75  XCLUSIVE].** </u
c4e0: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  l>.**.** The [SQ
c4f0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
c500: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65  ONCLOSE] flag me
c510: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ans the file sho
c520: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65  uld be.** delete
c530: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f  d when it is clo
c540: 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  sed.  ^The [SQLI
c550: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
c560: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62  CLOSE].** will b
c570: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64  e set for TEMP d
c580: 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65  atabases and the
c590: 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61  ir journals, tra
c5a0: 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61  nsient.** databa
c5b0: 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72  ses, and subjour
c5c0: 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nals..**.** ^The
c5d0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
c5e0: 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73  CLUSIVE] flag is
c5f0: 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20   always used in 
c600: 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  conjunction.** w
c610: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
c620: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61  OPEN_CREATE] fla
c630: 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74  g, which are bot
c640: 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e  h directly.** an
c650: 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f  alogous to the O
c660: 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41  _EXCL and O_CREA
c670: 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50  T flags of the P
c680: 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41  OSIX open().** A
c690: 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  PI.  The SQLITE_
c6a0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66  OPEN_EXCLUSIVE f
c6b0: 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64  lag, when paired
c6c0: 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51   with the .** SQ
c6d0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
c6e0: 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64  , is used to ind
c6f0: 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20  icate that file 
c700: 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a  should always.**
c710: 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64   be created, and
c720: 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65   that it is an e
c730: 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61  rror if it alrea
c740: 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74  dy exists..** It
c750: 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75   is <i>not</i> u
c760: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
c770: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
c780: 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f  be opened .** fo
c790: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65  r exclusive acce
c7a0: 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65  ss..**.** ^At le
c7b0: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74  ast szOsFile byt
c7c0: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65  es of memory are
c7d0: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
c7e0: 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20  Lite.** to hold 
c7f0: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69  the  [sqlite3_fi
c800: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61  le] structure pa
c810: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
c820: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
c830: 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70   xOpen.  The xOp
c840: 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e  en method does n
c850: 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c  ot have to.** al
c860: 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63  locate the struc
c870: 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20  ture; it should 
c880: 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e  just fill it in.
c890: 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74    Note that.** t
c8a0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
c8b0: 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c  must set the sql
c8c0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
c8d0: 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20  ds to either.** 
c8e0: 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33  a valid [sqlite3
c8f0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
c900: 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20  ect or to NULL. 
c910: 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a   xOpen must do.*
c920: 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74  * this even if t
c930: 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20  he open fails.  
c940: 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74  SQLite expects t
c950: 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hat the sqlite3_
c960: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a  file.pMethods.**
c970: 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65   element will be
c980: 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70   valid after xOp
c990: 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72  en returns regar
c9a0: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63  dless of the suc
c9b0: 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75  cess.** or failu
c9c0: 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20  re of the xOpen 
c9d0: 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71  call..**.** [[sq
c9e0: 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73  lite3_vfs.xAcces
c9f0: 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67  s]].** ^The flag
ca00: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41  s argument to xA
ca10: 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b  ccess() may be [
ca20: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
ca30: 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  ISTS].** to test
ca40: 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e   for the existen
ca50: 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72  ce of a file, or
ca60: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
ca70: 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a  READWRITE] to.**
ca80: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
ca90: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
caa0: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f   and writable, o
cab0: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
cac0: 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73  _READ].** to tes
cad0: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65  t whether a file
cae0: 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61   is at least rea
caf0: 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c  dable.   The fil
cb00: 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69  e can be a.** di
cb10: 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  rectory..**.** ^
cb20: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61  SQLite will alwa
cb30: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c  ys allocate at l
cb40: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b  east mxPathname+
cb50: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a  1 bytes for the.
cb60: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ** output buffer
cb70: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
cb80: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20   The exact size 
cb90: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  of the output bu
cba0: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20  ffer.** is also 
cbb0: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
cbc0: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d  meter to both  m
cbd0: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f  ethods. If the o
cbe0: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
cbf0: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
cc00: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
cc10: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
cc20: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
cc30: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
cc40: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
cc50: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
cc60: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
cc70: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
cc80: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
cc90: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
cca0: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
ccb0: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
ccc0: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
ccd0: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
cce0: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78  s(), xSleep(), x
ccf0: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61  CurrentTime(), a
cd00: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  nd xCurrentTimeI
cd10: 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66  nt64().** interf
cd20: 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72  aces are not str
cd30: 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20  ictly a part of 
cd40: 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20  the filesystem, 
cd50: 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  but they are.** 
cd60: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20  included in the 
cd70: 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f  VFS structure fo
cd80: 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a  r completeness..
cd90: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
cda0: 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74  ss() function at
cdb0: 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e  tempts to return
cdc0: 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a   nBytes bytes.**
cdd0: 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79   of good-quality
cde0: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
cdf0: 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75   zOut.  The retu
ce00: 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74  rn value is.** t
ce10: 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72  he actual number
ce20: 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e   of bytes of ran
ce30: 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
ce40: 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28  ..** The xSleep(
ce50: 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20  ) method causes 
ce60: 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65  the calling thre
ce70: 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20  ad to sleep for 
ce80: 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20  at.** least the 
ce90: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73  number of micros
cea0: 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e  econds given.  ^
ceb0: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
cec0: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
ced0: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61  urns a Julian Da
cee0: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65  y Number for the
cef0: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e   current date an
cf00: 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66  d time as.** a f
cf10: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
cf20: 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75  lue..** ^The xCu
cf30: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
cf40: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c   method returns,
cf50: 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20   as an integer, 
cf60: 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61  the Julian.** Da
cf70: 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c  y Number multipl
cf80: 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20  ied by 86400000 
cf90: 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d  (the number of m
cfa0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a  illiseconds in .
cfb0: 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79  ** a 24-hour day
cfc0: 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ).  .** ^SQLite 
cfd0: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75  will use the xCu
cfe0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
cff0: 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74   method to get t
d000: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61  he current.** da
d010: 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74  te and time if t
d020: 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76  hat method is av
d030: 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72  ailable (if iVer
d040: 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a  sion is 2 or .**
d050: 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65   greater and the
d060: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
d070: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61  r is not NULL) a
d080: 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63  nd will fall bac
d090: 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74  k.** to xCurrent
d0a0: 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65  Time() if xCurre
d0b0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73  ntTimeInt64() is
d0c0: 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
d0d0: 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73  .** ^The xSetSys
d0e0: 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53  temCall(), xGetS
d0f0: 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64  ystemCall(), and
d100: 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c   xNestSystemCall
d110: 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
d120: 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79   are not used by
d130: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
d140: 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61  .  These optiona
d150: 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  l interfaces are
d160: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20   provided.** by 
d170: 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61  some VFSes to fa
d180: 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67  cilitate testing
d190: 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65   of the VFS code
d1a0: 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20  . By overriding 
d1b0: 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73  .** system calls
d1c0: 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20   with functions 
d1d0: 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f  under its contro
d1e0: 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61  l, a test progra
d1f0: 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74  m can.** simulat
d200: 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72  e faults and err
d210: 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68  or conditions th
d220: 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69  at would otherwi
d230: 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a  se be difficult.
d240: 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65  ** or impossible
d250: 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65   to induce.  The
d260: 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63   set of system c
d270: 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65  alls that can be
d280: 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76   overridden.** v
d290: 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56  aries from one V
d2a0: 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61  FS to another, a
d2b0: 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73  nd from one vers
d2c0: 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ion of the same 
d2d0: 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65  VFS to the.** ne
d2e0: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
d2f0: 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65  s that use these
d300: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74   interfaces must
d310: 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72   be prepared for
d320: 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f   any.** or all o
d330: 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  f these interfac
d340: 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72  es to be NULL or
d350: 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76   for their behav
d360: 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a  ior to change.**
d370: 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73   from one releas
d380: 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20  e to the next.  
d390: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73  Applications mus
d3a0: 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f  t not attempt to
d3b0: 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f   access.** any o
d3c0: 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20  f these methods 
d3d0: 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  if the iVersion 
d3e0: 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65  of the VFS is le
d3f0: 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79  ss than 3..*/.ty
d400: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
d410: 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33  ite3_vfs sqlite3
d420: 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f  _vfs;.typedef vo
d430: 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73  id (*sqlite3_sys
d440: 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b  call_ptr)(void);
d450: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
d460: 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  vfs {.  int iVer
d470: 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20  sion;           
d480: 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65   /* Structure ve
d490: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75  rsion number (cu
d4a0: 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20  rrently 3) */.  
d4b0: 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20  int szOsFile;   
d4c0: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65           /* Size
d4d0: 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73   of subclassed s
d4e0: 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20  qlite3_file */. 
d4f0: 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b   int mxPathname;
d500: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
d510: 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61  imum file pathna
d520: 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73  me length */.  s
d530: 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78  qlite3_vfs *pNex
d540: 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20  t;      /* Next 
d550: 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a  registered VFS *
d560: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
d570: 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20  zName;       /* 
d580: 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72  Name of this vir
d590: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
d5a0: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
d5b0: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f  Data;          /
d5c0: 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70  * Pointer to app
d5d0: 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69  lication-specifi
d5e0: 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20  c data */.  int 
d5f0: 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
d600: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
d610: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
d620: 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20  3_file*,.       
d630: 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67          int flag
d640: 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67  s, int *pOutFlag
d650: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c  s);.  int (*xDel
d660: 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ete)(sqlite3_vfs
d670: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
d680: 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69  Name, int syncDi
d690: 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63  r);.  int (*xAcc
d6a0: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
d6b0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
d6c0: 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c  Name, int flags,
d6d0: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
d6e0: 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74    int (*xFullPat
d6f0: 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  hname)(sqlite3_v
d700: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
d710: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74  *zName, int nOut
d720: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
d730: 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e   void *(*xDlOpen
d740: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
d750: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
d760: 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28  ename);.  void (
d770: 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74  *xDlError)(sqlit
d780: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
d790: 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73  te, char *zErrMs
d7a0: 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78  g);.  void (*(*x
d7b0: 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76  DlSym)(sqlite3_v
d7c0: 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74  fs*,void*, const
d7d0: 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29   char *zSymbol))
d7e0: 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28  (void);.  void (
d7f0: 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74  *xDlClose)(sqlit
d800: 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b  e3_vfs*, void*);
d810: 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d  .  int (*xRandom
d820: 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  ness)(sqlite3_vf
d830: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
d840: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e  har *zOut);.  in
d850: 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69  t (*xSleep)(sqli
d860: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69  te3_vfs*, int mi
d870: 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69  croseconds);.  i
d880: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
d890: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
d8a0: 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74   double*);.  int
d8b0: 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72   (*xGetLastError
d8c0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
d8d0: 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20  int, char *);.  
d8e0: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
d8f0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
d900: 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68   version 1 of th
d910: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
d920: 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74  ect.  ** definit
d930: 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74  ion.  Those that
d940: 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65   follow are adde
d950: 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f  d in version 2 o
d960: 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69  r later.  */.  i
d970: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
d980: 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f  eInt64)(sqlite3_
d990: 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  vfs*, sqlite3_in
d9a0: 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  t64*);.  /*.  **
d9b0: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
d9c0: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
d9d0: 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68  ns 1 and 2 of th
d9e0: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
d9f0: 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20  ect..  ** Those 
da00: 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65  below are for ve
da10: 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61  rsion 3 and grea
da20: 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ter..  */.  int 
da30: 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xSetSystemCall
da40: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
da50: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
da60: 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  e, sqlite3_sysca
da70: 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74  ll_ptr);.  sqlit
da80: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28  e3_syscall_ptr (
da90: 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xGetSystemCall)
daa0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
dab0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
dac0: 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  );.  const char 
dad0: 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61  *(*xNextSystemCa
dae0: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
daf0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
db00: 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  ame);.  /*.  ** 
db10: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
db20: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
db30: 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66  s 1 through 3 of
db40: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
db50: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77  object..  ** New
db60: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
db70: 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72  ppended in figur
db80: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65  e versions.  The
db90: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76   iVersion.  ** v
dba0: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d  alue will increm
dbb0: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69  ent whenever thi
dbc0: 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f  s happens. .  */
dbd0: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
dbe0: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
dbf0: 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d  he xAccess VFS m
dc00: 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
dc10: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
dc20: 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nts can be used 
dc30: 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72  as the third par
dc40: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
dc50: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
dc60: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  of an [sqlite3_v
dc70: 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  fs] object.  The
dc80: 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77  y determine.** w
dc90: 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d  hat kind of perm
dca0: 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63  issions the xAcc
dcb0: 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f  ess method is lo
dcc0: 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69  oking for..** Wi
dcd0: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
dce0: 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63  _EXISTS, the xAc
dcf0: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73  cess method.** s
dd00: 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65  imply checks whe
dd10: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78  ther the file ex
dd20: 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51  ists..** With SQ
dd30: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
dd40: 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65  WRITE, the xAcce
dd50: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
dd60: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
dd70: 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20  named directory 
dd80: 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65  is both readable
dd90: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a   and writable.**
dda0: 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73   (in other words
ddb0: 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62  , if files can b
ddc0: 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64  e added, removed
ddd0: 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69  , and renamed wi
dde0: 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65  thin.** the dire
ddf0: 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53  ctory)..** The S
de00: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
de10: 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20  DWRITE constant 
de20: 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65  is currently use
de30: 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a  d only by the.**
de40: 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
de50: 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20  ectory pragma], 
de60: 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c  though this coul
de70: 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  d change in a fu
de80: 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
de90: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69  of SQLite..** Wi
dea0: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
deb0: 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65  _READ, the xAcce
dec0: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
ded0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
dee0: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
def0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  .  The SQLITE_AC
df00: 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61  CESS_READ consta
df10: 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74  nt is.** current
df20: 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67  ly unused, thoug
df30: 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73  h it might be us
df40: 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72  ed in a future r
df50: 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
df60: 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
df70: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
df80: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e  ISTS    0.#defin
df90: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
dfa0: 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a  READWRITE 1   /*
dfb0: 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20   Used by PRAGMA 
dfc0: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
dfd0: 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tory */.#define 
dfe0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
dff0: 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55  AD      2   /* U
e000: 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  nused */../*.** 
e010: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
e020: 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b  for the xShmLock
e030: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
e040: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
e050: 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
e060: 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63   the various loc
e070: 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a  king operations.
e080: 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68  ** allowed by th
e090: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
e0a0: 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d of [sqlite3_io
e0b0: 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a  _methods].  The.
e0c0: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65  ** following are
e0d0: 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20   the only legal 
e0e0: 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20  combinations of 
e0f0: 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20  flags to the.** 
e100: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a  xShmLock method:
e110: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
e120: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
e130: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
e140: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
e150: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
e160: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
e170: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e  XCLUSIVE.** <li>
e180: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
e190: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
e1a0: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
e1b0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
e1c0: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
e1d0: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75  EXCLUSIVE.** </u
e1e0: 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e  l>.**.** When un
e1f0: 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d  locking, the sam
e200: 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c  e SHARED or EXCL
e210: 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20  USIVE flag must 
e220: 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a  be supplied as.*
e230: 2a 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74  * was given no t
e240: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
e250: 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54   lock.  .**.** T
e260: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
e270: 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f  od can transitio
e280: 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  n between unlock
e290: 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72  ed and SHARED or
e2a0: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f  .** between unlo
e2b0: 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49  cked and EXCLUSI
e2c0: 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74  VE.  It cannot t
e2d0: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
e2e0: 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20  n SHARED.** and 
e2f0: 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64  EXCLUSIVE..*/.#d
e300: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
e310: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a  _UNLOCK       1.
e320: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
e330: 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  HM_LOCK         
e340: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
e350: 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20  _SHM_SHARED     
e360: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
e370: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
e380: 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      8../*.** CAP
e390: 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78  I3REF: Maximum x
e3a0: 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a  ShmLock index.**
e3b0: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
e3c0: 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69   method on [sqli
e3d0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
e3e0: 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a  may use values.*
e3f0: 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  * between 0 and 
e400: 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64  this upper bound
e410: 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22   as its "offset"
e420: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68   argument..** Th
e430: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69  e SQLite core wi
e440: 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74  ll never attempt
e450: 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72   to acquire or r
e460: 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b  elease a.** lock
e470: 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73   outside of this
e480: 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e   range.*/.#defin
e490: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f  e SQLITE_SHM_NLO
e4a0: 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a  CK        8.../*
e4b0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
e4c0: 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c  itialize The SQL
e4d0: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
e4e0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
e4f0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
e500: 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  ine initializes 
e510: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69  the.** SQLite li
e520: 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c  brary.  ^The sql
e530: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
e540: 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c  routine.** deall
e550: 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75  ocates any resou
e560: 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61  rces that were a
e570: 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
e580: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
e590: 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
e5a0: 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64  nes are designed
e5b0: 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65   to aid in proce
e5c0: 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
e5d0: 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77  n and.** shutdow
e5e0: 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79  n on embedded sy
e5f0: 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74  stems.  Workstat
e600: 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ion applications
e610: 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65   using.** SQLite
e620: 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74   normally do not
e630: 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20   need to invoke 
e640: 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20  either of these 
e650: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
e660: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
e670: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
e680: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
e690: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a   call if it is.*
e6a0: 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  * the first time
e6b0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
e6c0: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
e6d0: 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65   during the life
e6e0: 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70  time of.** the p
e6f0: 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74  rocess, or if it
e700: 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69   is the first ti
e710: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
e720: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
e730: 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
e740: 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  a call to sqlite
e750: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e  3_shutdown().  ^
e760: 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69  (Only an effecti
e770: 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71  ve call.** of sq
e780: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
e790: 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74  () does any init
e7a0: 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c  ialization.  All
e7b0: 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   other calls.** 
e7c0: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
e7d0: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63  ops.)^.**.** A c
e7e0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
e7f0: 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20  hutdown() is an 
e800: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
e810: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
e820: 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73  rst.** call to s
e830: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
e840: 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74  ) since the last
e850: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
e860: 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a  ize().  ^(Only.*
e870: 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  * an effective c
e880: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
e890: 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61  hutdown() does a
e8a0: 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74  ny deinitializat
e8b0: 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65  ion..** All othe
e8c0: 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f  r valid calls to
e8d0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
e8e0: 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73  n() are harmless
e8f0: 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a   no-ops.)^.**.**
e900: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
e910: 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66  tialize() interf
e920: 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66  ace is threadsaf
e930: 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73  e, but sqlite3_s
e940: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20  hutdown().** is 
e950: 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  not.  The sqlite
e960: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74  3_shutdown() int
e970: 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79  erface must only
e980: 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
e990: 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65  a.** single thre
e9a0: 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64  ad.  All open [d
e9b0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
e9c0: 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f  ons] must be clo
e9d0: 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f  sed and all.** o
e9e0: 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f  ther SQLite reso
e9f0: 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65  urces must be de
ea00: 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20  allocated prior 
ea10: 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73  to invoking.** s
ea20: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
ea30: 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f  )..**.** Among o
ea40: 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71  ther things, ^sq
ea50: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ea60: 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a  () will invoke.*
ea70: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
ea80: 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c  t().  Similarly,
ea90: 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   ^sqlite3_shutdo
eaa0: 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76  wn().** will inv
eab0: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  oke sqlite3_os_e
eac0: 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nd()..**.** ^The
ead0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
eae0: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ize() routine re
eaf0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
eb00: 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a  ] on success..**
eb10: 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65   ^If for some re
eb20: 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ason, sqlite3_in
eb30: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e  itialize() is un
eb40: 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69  able to initiali
eb50: 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72  ze.** the librar
eb60: 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73  y (perhaps it is
eb70: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
eb80: 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73  ate a needed res
eb90: 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73  ource such.** as
eba0: 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74   a mutex) it ret
ebb0: 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63  urns an [error c
ebc0: 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20  ode] other than 
ebd0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
ebe0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
ebf0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
ec00: 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69  tine is called i
ec10: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e  nternally by man
ec20: 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  y other.** SQLit
ec30: 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20  e interfaces so 
ec40: 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74  that an applicat
ec50: 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73  ion usually does
ec60: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20   not need to.** 
ec70: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
ec80: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
ec90: 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70  ctly.  For examp
eca0: 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  le, [sqlite3_ope
ecb0: 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71  n()].** calls sq
ecc0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ecd0: 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65  () so the SQLite
ece0: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65   library will be
ecf0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
ed00: 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68  * initialized wh
ed10: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  en [sqlite3_open
ed20: 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66  ()] is called if
ed30: 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69   it has not be i
ed40: 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c  nitialized.** al
ed50: 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72  ready.  ^However
ed60: 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  , if SQLite is c
ed70: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
ed80: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
ed90: 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69  TOINIT].** compi
eda0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
edb0: 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74  then the automat
edc0: 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ic calls to sqli
edd0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
ede0: 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20  .** are omitted 
edf0: 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
ee00: 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71  ion must call sq
ee10: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ee20: 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70  () directly.** p
ee30: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
ee40: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
ee50: 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d  nterface.  For m
ee60: 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69  aximum portabili
ee70: 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63  ty,.** it is rec
ee80: 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
ee90: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79  plications alway
eea0: 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  s invoke sqlite3
eeb0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
eec0: 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20   directly prior 
eed0: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
eee0: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
eef0: 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c  ace.  Future rel
ef00: 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69  eases.** of SQLi
ef10: 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74  te may require t
ef20: 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  his.  In other w
ef30: 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69  ords, the behavi
ef40: 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20  or exhibited.** 
ef50: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
ef60: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
ef70: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
ef80: 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65  IT] might become
ef90: 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20   the.** default 
efa0: 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65  behavior in some
efb0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
efc0: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
efd0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
efe0: 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64  init() routine d
eff0: 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  oes operating-sy
f000: 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a  stem specific.**
f010: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
f020: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
f030: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
f040: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
f050: 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74  routine undoes t
f060: 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c  he effect of sql
f070: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
f080: 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a   Typical tasks.*
f090: 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74  * performed by t
f0a0: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e  hese routines in
f0b0: 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  clude allocation
f0c0: 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e   or deallocation
f0d0: 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65  .** of static re
f0e0: 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c  sources, initial
f0f0: 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61  ization of globa
f100: 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20  l variables,.** 
f110: 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66  setting up a def
f120: 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
f130: 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65  s] module, or se
f140: 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65  tting up.** a de
f150: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
f160: 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ion using [sqlit
f170: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
f180: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
f190: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
f1a0: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73   invoke either s
f1b0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
f1c0: 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  .** or sqlite3_o
f1d0: 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79  s_end() directly
f1e0: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
f1f0: 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69  on should only i
f200: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
f210: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
f220: 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  d sqlite3_shutdo
f230: 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74  wn().  The sqlit
f240: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
f250: 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c  interface is cal
f260: 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  led automaticall
f270: 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  y by sqlite3_ini
f280: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a  tialize() and.**
f290: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
f2a0: 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73  ) is called by s
f2b0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f2c0: 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a  ).  Appropriate.
f2d0: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
f2e0: 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  ns for sqlite3_o
f2f0: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
f300: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
f310: 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20   are built into 
f320: 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69  SQLite when it i
f330: 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55  s compiled for U
f340: 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72  nix, Windows, or
f350: 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b   OS/2..** When [
f360: 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20  custom builds | 
f370: 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20  built for other 
f380: 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75  platforms].** (u
f390: 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
f3a0: 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d  _OS_OTHER=1] com
f3b0: 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
f3c0: 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61  ion) the applica
f3d0: 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79  tion must supply
f3e0: 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c   a suitable impl
f3f0: 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  ementation for.*
f400: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
f410: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
f420: 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70  os_end().  An ap
f430: 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69  plication-suppli
f440: 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ed.** implementa
f450: 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
f460: 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c  os_init() or sql
f470: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
f480: 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51   must return [SQ
f490: 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
f4a0: 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68  ess and some oth
f4b0: 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  er [error code] 
f4c0: 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e  upon.** failure.
f4d0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
f4e0: 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29  initialize(void)
f4f0: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68  ;.int sqlite3_sh
f500: 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e  utdown(void);.in
f510: 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  t sqlite3_os_ini
f520: 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  t(void);.int sql
f530: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64  ite3_os_end(void
f540: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
f550: 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20  EF: Configuring 
f560: 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
f570: 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ry.**.** The sql
f580: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
f590: 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
f5a0: 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63  to make global c
f5b0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
f5c0: 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74  changes to SQLit
f5d0: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75  e in order to tu
f5e0: 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  ne SQLite to the
f5f0: 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20   specific needs 
f600: 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
f610: 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61  ation.  The defa
f620: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
f630: 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  n is recommended
f640: 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70   for most.** app
f650: 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f  lications and so
f660: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
f670: 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63   usually not nec
f680: 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a  essary.  It is.*
f690: 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75  * provided to su
f6a0: 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69  pport rare appli
f6b0: 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75  cations with unu
f6c0: 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  sual needs..**.*
f6d0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
f6e0: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
f6f0: 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61   is not threadsa
f700: 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  fe.  The applica
f710: 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73  tion.** must ins
f720: 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65  ure that no othe
f730: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
f740: 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20  ces are invoked 
f750: 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65  by other.** thre
f760: 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65  ads while sqlite
f770: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75  3_config() is ru
f780: 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d  nning.  Furtherm
f790: 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ore, sqlite3_con
f7a0: 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c  fig().** may onl
f7b0: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69  y be invoked pri
f7c0: 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e  or to library in
f7d0: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69  itialization usi
f7e0: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  ng.** [sqlite3_i
f7f0: 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20  nitialize()] or 
f800: 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62  after shutdown b
f810: 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  y [sqlite3_shutd
f820: 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73  own()]..** ^If s
f830: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
f840: 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  is called after 
f850: 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
f860: 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72  ize()] and befor
f870: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  e.** [sqlite3_sh
f880: 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69  utdown()] then i
f890: 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51  t will return SQ
f8a0: 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20  LITE_MISUSE..** 
f8b0: 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74  Note, however, t
f8c0: 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e  hat ^sqlite3_con
f8d0: 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c  fig() can be cal
f8e0: 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  led as part of t
f8f0: 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
f900: 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69  tion of an appli
f910: 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b  cation-defined [
f920: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
f930: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  )]..**.** The fi
f940: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
f950: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
f960: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a   is an integer.*
f970: 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  * [configuration
f980: 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65   option] that de
f990: 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74  termines.** what
f9a0: 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c   property of SQL
f9b0: 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e  ite is to be con
f9c0: 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71  figured.  Subseq
f9d0: 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a  uent arguments.*
f9e0: 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  * vary depending
f9f0: 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75   on the [configu
fa00: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a  ration option].*
fa10: 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  * in the first a
fa20: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
fa30: 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61  When a configura
fa40: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73  tion option is s
fa50: 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  et, sqlite3_conf
fa60: 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51  ig() returns [SQ
fa70: 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66  LITE_OK]..** ^If
fa80: 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75   the option is u
fa90: 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65  nknown or SQLite
faa0: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65   is unable to se
fab0: 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20  t the option.** 
fac0: 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  then this routin
fad0: 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d  e returns a non-
fae0: 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
faf0: 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
fb00: 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e  3_config(int, ..
fb10: 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
fb20: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64  REF: Configure d
fb30: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
fb40: 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ons.**.** The sq
fb50: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
fb60: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
fb70: 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66  sed to make conf
fb80: 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
fb90: 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62  nges to a [datab
fba0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
fbb0: 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20    The interface 
fbc0: 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a  is similar to.**
fbd0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
fbe0: 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20  ()] except that 
fbf0: 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c  the changes appl
fc00: 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a  y to a single.**
fc10: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
fc20: 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65  ction] (specifie
fc30: 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
fc40: 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20  rgument)..**.** 
fc50: 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
fc60: 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  ent to sqlite3_d
fc70: 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e  b_config(D,V,...
fc80: 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51  )  is the.** [SQ
fc90: 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
fca0: 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67  OKASIDE | config
fcb0: 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20  uration verb] - 
fcc0: 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20  an integer code 
fcd0: 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74  .** that indicat
fce0: 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f  es what aspect o
fcf0: 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
fd00: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62  connection] is b
fd10: 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e  eing configured.
fd20: 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61  .** Subsequent a
fd30: 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65  rguments vary de
fd40: 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63  pending on the c
fd50: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72  onfiguration ver
fd60: 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20  b..**.** ^Calls 
fd70: 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  to sqlite3_db_co
fd80: 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51  nfig() return SQ
fd90: 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f  LITE_OK if and o
fda0: 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61  nly if.** the ca
fdb0: 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  ll is considered
fdc0: 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a   successful..*/.
fdd0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  int sqlite3_db_c
fde0: 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20  onfig(sqlite3*, 
fdf0: 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f  int op, ...);../
fe00: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
fe10: 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
fe20: 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20   Routines.**.** 
fe30: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
fe40: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
fe50: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
fe60: 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a   between SQLite.
fe70: 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c  ** and low-level
fe80: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
fe90: 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  on routines..**.
fea0: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
feb0: 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f  s used in only o
fec0: 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20  ne place in the 
fed0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
fee0: 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  ..** A pointer t
fef0: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
ff00: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
ff10: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  the argument to.
ff20: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
ff30: 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63  ig()] when the c
ff40: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
ff50: 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54  ion is.** [SQLIT
ff60: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
ff70: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
ff80: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20  IG_GETMALLOC].  
ff90: 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20  .** By creating 
ffa0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
ffb0: 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e  his object.** an
ffc0: 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  d passing it to 
ffd0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
ffe0: 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
fff0: 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69  MALLOC]).** duri
10000 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
10010 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
10020 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20   can specify an 
10030 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
10040 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10050 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53   subsystem for S
10060 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72  QLite to use for
10070 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64   all of its.** d
10080 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65  ynamic memory ne
10090 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  eds..**.** Note 
100a0 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65  that SQLite come
100b0 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b  s with several [
100c0 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
100d0 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74  allocators].** t
100e0 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c  hat are perfectl
100f0 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74  y adequate for t
10100 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20  he overwhelming 
10110 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  majority of appl
10120 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20  ications.** and 
10130 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74  that this object
10140 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20   is only useful 
10150 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69  to a tiny minori
10160 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
10170 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69  ns.** with speci
10180 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c  alized memory al
10190 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65  location require
101a0 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a  ments.  This obj
101b0 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75  ect is.** also u
101c0 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
101d0 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20  ng of SQLite in 
101e0 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79  order to specify
101f0 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
10200 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
10210 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  tor that simulat
10220 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66  es memory out-of
10230 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f  -memory conditio
10240 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74  ns in.** order t
10250 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51  o verify that SQ
10260 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72  Lite recovers gr
10270 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75  acefully from su
10280 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73  ch.** conditions
10290 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c  ..**.** The xMal
102a0 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61  loc, xRealloc, a
102b0 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73  nd xFree methods
102c0 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20   must work like 
102d0 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c  the.** malloc(),
102e0 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66   realloc() and f
102f0 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20  ree() functions 
10300 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
10310 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20  d C library..** 
10320 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
10330 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  es that the seco
10340 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
10350 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c  * xRealloc is al
10360 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74  ways a value ret
10370 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72  urned by a prior
10380 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75   call to xRoundu
10390 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73  p..**.** xSize s
103a0 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  hould return the
103b0 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20   allocated size 
103c0 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  of a memory allo
103d0 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f  cation.** previo
103e0 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  usly obtained fr
103f0 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52  om xMalloc or xR
10400 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c  ealloc.  The all
10410 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69  ocated size.** i
10420 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73  s always at leas
10430 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20  t as big as the 
10440 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62  requested size b
10450 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
10460 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75  ..**.** The xRou
10470 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75  ndup method retu
10480 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62  rns what would b
10490 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  e the allocated 
104a0 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d  size of.** a mem
104b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67  ory allocation g
104c0 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61  iven a particula
104d0 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  r requested size
104e0 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a  .  Most memory.*
104f0 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  * allocators rou
10500 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c  nd up memory all
10510 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73  ocations at leas
10520 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75  t to the next mu
10530 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20  ltiple.** of 8. 
10540 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73   Some allocators
10550 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c   round up to a l
10560 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  arger multiple o
10570 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20  r to a power of 
10580 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f  2..** Every memo
10590 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
105a0 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20  quest coming in 
105b0 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33  through [sqlite3
105c0 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72  _malloc()].** or
105d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
105e0 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73  c()] first calls
105f0 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78   xRoundup.  If x
10600 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20  Roundup returns 
10610 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73  0, .** that caus
10620 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  es the correspon
10630 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ding memory allo
10640 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a  cation to fail..
10650 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20  **.** The xInit 
10660 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a  method initializ
10670 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  es the memory al
10680 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78  locator.  For ex
10690 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67  ample,.** it mig
106a0 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20  ht allocate any 
106b0 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20  require mutexes 
106c0 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e  or initialize in
106d0 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73  ternal data.** s
106e0 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20  tructures.  The 
106f0 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
10700 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64   is invoked (ind
10710 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b  irectly) by.** [
10720 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
10730 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64  ()] and should d
10740 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65  eallocate any re
10750 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64  sources acquired
10760 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54  .** by xInit.  T
10770 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e  he pAppData poin
10780 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74  ter is used as t
10790 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
107a0 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e  r to.** xInit an
107b0 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a  d xShutdown..**.
107c0 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20  ** SQLite holds 
107d0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
107e0 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d  X_STATIC_MASTER]
107f0 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69   mutex when it i
10800 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49  nvokes.** the xI
10810 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74  nit method, so t
10820 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
10830 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65  need not be thre
10840 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20  adsafe.  The.** 
10850 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
10860 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20   is only called 
10870 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68  from [sqlite3_sh
10880 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20  utdown()] so it 
10890 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64  does.** not need
108a0 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66   to be threadsaf
108b0 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61  e either.  For a
108c0 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73  ll other methods
108d0 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64  , SQLite.** hold
108e0 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
108f0 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20  TEX_STATIC_MEM] 
10900 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73  mutex as long as
10910 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
10920 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
10930 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
10940 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  option is turned
10950 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74   on (which.** it
10960 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20   is by default) 
10970 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f  and so the metho
10980 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ds are automatic
10990 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e  ally serialized.
109a0 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20  .** However, if 
109b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
109c0 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73  EMSTATUS] is dis
109d0 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20  abled, then the 
109e0 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73  other.** methods
109f0 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
10a00 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65  afe or else make
10a10 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e   their own arran
10a20 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73  gements for.** s
10a30 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  erialization..**
10a40 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
10a50 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e  never invoke xIn
10a60 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f  it() more than o
10a70 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69  nce without an i
10a80 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61  ntervening.** ca
10a90 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28  ll to xShutdown(
10aa0 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  )..*/.typedef st
10ab0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
10ac0 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
10ad0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  _mem_methods;.st
10ae0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
10af0 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69  _methods {.  voi
10b00 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e  d *(*xMalloc)(in
10b10 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  t);         /* M
10b20 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10b30 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
10b40 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69  oid (*xFree)(voi
10b50 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  d*);          /*
10b60 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c   Free a prior al
10b70 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  location */.  vo
10b80 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28  id *(*xRealloc)(
10b90 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20  void*,int);  /* 
10ba0 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61  Resize an alloca
10bb0 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
10bc0 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20  xSize)(void*);  
10bd0 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75           /* Retu
10be0 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  rn the size of a
10bf0 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
10c00 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70    int (*xRoundup
10c10 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
10c20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71   /* Round up req
10c30 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c  uest size to all
10c40 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a  ocation size */.
10c50 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76    int (*xInit)(v
10c60 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
10c70 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74   /* Initialize t
10c80 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
10c90 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  tor */.  void (*
10ca0 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a  xShutdown)(void*
10cb0 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69  );      /* Deini
10cc0 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
10cd0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
10ce0 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
10cf0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
10d00 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20   /* Argument to 
10d10 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75  xInit() and xShu
10d20 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f  tdown() */.};../
10d30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
10d40 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
10d50 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
10d60 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  : {configuration
10d70 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54   option}.**.** T
10d80 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
10d90 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
10da0 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
10db0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
10dc0 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
10dd0 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73  ssed as the firs
10de0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
10df0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
10e00 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
10e10 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
10e20 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
10e30 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
10e40 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
10e50 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
10e60 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
10e70 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
10e80 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
10e90 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
10ea0 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
10eb0 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
10ec0 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
10ed0 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b  config()] to mak
10ee0 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74  e sure that.** t
10ef0 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20  he call worked. 
10f00 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
10f10 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
10f20 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
10f30 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
10f40 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
10f50 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
10f60 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
10f70 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
10f80 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
10f90 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
10fa0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
10fb0 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  LETHREAD]] <dt>S
10fc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
10fd0 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  GLETHREAD</dt>.*
10fe0 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
10ff0 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
11000 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
11010 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
11020 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
11030 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c  g mode] to Singl
11040 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  e-thread.  In ot
11050 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
11060 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  sables.** all mu
11070 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20  texing and puts 
11080 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f  SQLite into a mo
11090 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20  de where it can 
110a0 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20  only be used.** 
110b0 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65  by a single thre
110c0 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  ad.   ^If SQLite
110d0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
110e0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
110f0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
11100 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
11110 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
11120 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
11130 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
11140 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  e to change the 
11150 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
11160 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c   from its defaul
11170 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69  t.** value of Si
11180 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20  ngle-thread and 
11190 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  so [sqlite3_conf
111a0 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
111b0 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  n .** [SQLITE_ER
111c0 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
111d0 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
111e0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
111f0 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  AD.** configurat
11200 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
11210 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11220 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
11230 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
11240 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
11250 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
11260 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
11270 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
11280 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
11290 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
112a0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
112b0 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64   to Multi-thread
112c0 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
112d0 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
112e0 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64  * mutexing on [d
112f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11300 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
11310 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
11320 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ects..** The app
11330 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70  lication is resp
11340 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69  onsible for seri
11350 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74  alizing access t
11360 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  o.** [database c
11370 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
11380 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
11390 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65  ents].  But othe
113a0 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65  r mutexes.** are
113b0 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74   enabled so that
113c0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
113d0 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61  safe to use in a
113e0 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a   multi-threaded.
113f0 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61  ** environment a
11400 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f  s long as no two
11410 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74   threads attempt
11420 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
11430 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
11440 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65  nnection] at the
11450 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66   same time.  ^If
11460 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
11470 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
11480 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
11490 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
114a0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
114b0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
114c0 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
114d0 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
114e0 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64  the Multi-thread
114f0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
11500 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
11510 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
11520 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
11530 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
11540 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
11550 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
11560 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61  THREAD configura
11570 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
11580 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
11590 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
115a0 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ED]] <dt>SQLITE_
115b0 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
115c0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
115d0 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
115e0 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
115f0 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
11600 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
11610 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
11620 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49  to Serialized. I
11630 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
11640 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c  his option enabl
11650 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65  es.** all mutexe
11660 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20  s including the 
11670 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74  recursive.** mut
11680 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  exes on [databas
11690 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
116a0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
116b0 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
116c0 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20  ** In this mode 
116d0 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65  (which is the de
116e0 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74  fault when SQLit
116f0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
11700 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  th.** [SQLITE_TH
11710 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65  READSAFE=1]) the
11720 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
11730 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69  will itself seri
11740 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20  alize access.** 
11750 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  to [database con
11760 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
11770 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
11780 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a  ts] so that the.
11790 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  ** application i
117a0 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68  s free to use th
117b0 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
117c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20   connection] or 
117d0 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65  the.** same [pre
117e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
117f0 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68   in different th
11800 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
11810 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53  e time..** ^If S
11820 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
11830 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
11840 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
11850 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
11860 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
11870 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
11880 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
11890 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
118a0 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e Serialized [th
118b0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
118c0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
118d0 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
118e0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
118f0 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
11900 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
11910 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
11920 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
11930 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
11940 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
11950 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  IG_MALLOC]] <dt>
11960 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
11970 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
11980 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
11990 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
119a0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
119b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
119c0 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
119d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
119e0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
119f0 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ure.  The argume
11a00 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
11a10 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
11a20 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
11a30 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
11a40 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
11a50 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d  lace of.** the m
11a60 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11a70 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
11a80 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e  into SQLite.)^ ^
11a90 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20  SQLite makes.** 
11aa0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
11ab0 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
11ac0 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
11ad0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
11ae0 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65   structure.** be
11af0 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65  fore the [sqlite
11b00 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c  3_config()] call
11b10 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a   returns.</dd>.*
11b20 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
11b30 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d  NFIG_GETMALLOC]]
11b40 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
11b50 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74  IG_GETMALLOC</dt
11b60 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
11b70 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
11b80 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
11b90 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
11ba0 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
11bb0 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
11bc0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
11bd0 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
11be0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
11bf0 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
11c00 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
11c10 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
11c20 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79  y defined memory
11c30 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
11c40 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
11c50 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
11c60 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
11c70 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  he default memor
11c80 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
11c90 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
11ca0 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d  wrapper that sim
11cb0 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20  ulations memory 
11cc0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
11cd0 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20  re or.** tracks 
11ce0 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f  memory usage, fo
11cf0 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e  r example. </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 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
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 4d 45 4d 53 54 41 54 55 53 3c 2f  NFIG_MEMSTATUS</
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 74 61 6b 65 73 20 73  s option takes s
11d60 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
11d70 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65  f type int, inte
11d80 72 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a  rpreted as a .**
11d90 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20   boolean, which 
11da0 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
11db0 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69  les the collecti
11dc0 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c  on of memory all
11dd0 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74  ocation .** stat
11de0 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d  istics. ^(When m
11df0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11e00 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
11e10 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a  disabled, the .*
11e20 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69  * following SQLi
11e30 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65  te interfaces be
11e40 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69  come non-operati
11e50 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a  onal:.**   <ul>.
11e60 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
11e70 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
11e80 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
11e90 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
11ea0 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c  water()].**   <l
11eb0 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  i> [sqlite3_soft
11ec0 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d  _heap_limit64()]
11ed0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
11ee0 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a  te3_status()].**
11ef0 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d     </ul>)^.** ^M
11f00 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11f10 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
11f20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
11f30 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65  lt unless SQLite
11f40 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
11f50 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46  with [SQLITE_DEF
11f60 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d  AULT_MEMSTATUS]=
11f70 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  0 in which case 
11f80 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
11f90 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
11fa0 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
11fb0 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64  default..** </dd
11fc0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
11fd0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
11fe0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
11ff0 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e  FIG_SCRATCH</dt>
12000 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
12010 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
12020 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
12030 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
12040 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a  te can use for.*
12050 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  * scratch memory
12060 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72  .  There are thr
12070 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41  ee arguments:  A
12080 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79   pointer an 8-by
12090 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65  te.** aligned me
120a0 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d  mory buffer from
120b0 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74   which the scrat
120c0 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77  ch allocations w
120d0 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c  ill be.** drawn,
120e0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
120f0 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  h scratch alloca
12100 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e  tion (sz),.** an
12110 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d the maximum nu
12120 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20  mber of scratch 
12130 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e  allocations (N).
12140 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75    The sz.** argu
12150 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d  ment must be a m
12160 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a  ultiple of 16..*
12170 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
12180 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70  ment must be a p
12190 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62  ointer to an 8-b
121a0 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66  yte aligned buff
121b0 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  er.** of at leas
121c0 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
121d0 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  memory..** ^SQLi
121e0 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d  te will use no m
121f0 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72  ore than two scr
12200 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72  atch buffers per
12210 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20   thread.  So.** 
12220 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20  N should be set 
12230 74 6f 20 74 77 69 63 65 20 74 68 65 20 65 78 70  to twice the exp
12240 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75  ected maximum nu
12250 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e  mber of threads.
12260 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
12270 20 6e 65 76 65 72 20 72 65 71 75 69 72 65 20 61   never require a
12280 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20   scratch buffer 
12290 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61  that is more tha
122a0 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65  n 6.** times the
122b0 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73   database page s
122c0 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  ize. ^If SQLite 
122d0 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69  needs needs addi
122e0 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63  tional.** scratc
122f0 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20  h memory beyond 
12300 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
12310 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75   by this configu
12320 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74  ration option, t
12330 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hen .** [sqlite3
12340 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20  _malloc()] will 
12350 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
12360 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65  n the memory nee
12370 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ded.</dd>.**.** 
12380 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12390 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e  PAGECACHE]] <dt>
123a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
123b0 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  GECACHE</dt>.** 
123c0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
123d0 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
123e0 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
123f0 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  er that SQLite c
12400 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  an use for.** th
12410 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
12420 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64  cache with the d
12430 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68  efault page cach
12440 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
12450 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66  .  .** This conf
12460 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64  iguration should
12470 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20   not be used if 
12480 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
12490 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61  efine page.** ca
124a0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
124b0 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69  on is loaded usi
124c0 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  ng the SQLITE_CO
124d0 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74  NFIG_PCACHE2 opt
124e0 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ion..** There ar
124f0 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
12500 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
12510 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38  : A pointer to 8
12520 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a  -byte aligned.**
12530 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a   memory, the siz
12540 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62  e of each page b
12550 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20  uffer (sz), and 
12560 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  the number of pa
12570 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20  ges (N)..** The 
12580 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  sz argument shou
12590 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f  ld be the size o
125a0 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61  f the largest da
125b0 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28  tabase page.** (
125c0 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62  a power of two b
125d0 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33  etween 512 and 3
125e0 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74  2768) plus a lit
125f0 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61  tle extra for ea
12600 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65  ch.** page heade
12610 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68 65  r.  ^The page he
12620 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20  ader size is 20 
12630 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65  to 40 bytes depe
12640 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20  nding on.** the 
12650 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72  host architectur
12660 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c  e.  ^It is harml
12670 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20  ess, apart from 
12680 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72  the wasted memor
12690 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a  y,.** to make sz
126a0 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61   a little too la
126b0 72 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a  rge.  The first.
126c0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
126d0 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61  ld point to an a
126e0 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20  llocation of at 
126f0 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
12700 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e   of memory..** ^
12710 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
12720 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69  the memory provi
12730 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ded by the first
12740 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74   argument to sat
12750 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f  isfy its.** memo
12760 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65  ry needs for the
12770 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74   first N pages t
12780 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63  hat it adds to c
12790 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74  ache.  ^If addit
127a0 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61  ional.** page ca
127b0 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65  che memory is ne
127c0 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74  eded beyond what
127d0 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
127e0 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65  this option, the
127f0 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73  n.** SQLite goes
12800 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
12810 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61  loc()] for the a
12820 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67  dditional storag
12830 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20  e space..** The 
12840 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66  pointer in the f
12850 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
12860 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64  st.** be aligned
12870 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
12880 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
12890 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
128a0 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
128b0 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64  be undefined.</d
128c0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
128d0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20  E_CONFIG_HEAP]] 
128e0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
128f0 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  G_HEAP</dt>.** <
12900 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
12910 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
12920 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
12930 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  r that SQLite wi
12940 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c  ll use.** for al
12950 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63  l of its dynamic
12960 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12970 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20  on needs beyond 
12980 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a  those provided.*
12990 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45  * for by [SQLITE
129a0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
129b0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   and [SQLITE_CON
129c0 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
129d0 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72  ** There are thr
129e0 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e  ee arguments: An
129f0 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
12a00 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
12a10 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75  emory,.** the nu
12a20 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
12a30 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66   the memory buff
12a40 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69  er, and the mini
12a50 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
12a60 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ize..** ^If the 
12a70 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
12a80 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
12a90 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  r) is NULL, then
12aa0 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a   SQLite reverts.
12ab0 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20  ** to using its 
12ac0 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
12ad0 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79  llocator (the sy
12ae0 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d  stem malloc() im
12af0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a  plementation),.*
12b00 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72  * undoing any pr
12b10 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ior invocation o
12b20 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
12b30 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74  _MALLOC].  ^If t
12b40 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69  he.** memory poi
12b50 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
12b60 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c   and either [SQL
12b70 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
12b80 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  S3] or.** [SQLIT
12b90 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35  E_ENABLE_MEMSYS5
12ba0 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74  ] are defined, t
12bb0 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74  hen the alternat
12bc0 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ive memory.** al
12bd0 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67  locator is engag
12be0 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c  ed to handle all
12bf0 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f   of SQLites memo
12c00 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
12c10 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  eds..** The firs
12c20 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
12c30 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d  emory pointer) m
12c40 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
12c50 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62  o an 8-byte.** b
12c60 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65  oundary or subse
12c70 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f  quent behavior o
12c80 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  f SQLite will be
12c90 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
12ca0 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
12cb0 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61  ation size is ca
12cc0 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52  pped at 2**12. R
12cd0 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73  easonable values
12ce0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69  .** for the mini
12cf0 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
12d00 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72  ize are 2**5 thr
12d10 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a  ough 2**8.</dd>.
12d20 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
12d30 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64  ONFIG_MUTEX]] <d
12d40 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12d50 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
12d60 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
12d70 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
12d80 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
12d90 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
12da0 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
12db0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
12dc0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
12dd0 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67  ucture.  The arg
12de0 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
12df0 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
12e00 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72  ow-level mutex r
12e10 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
12e20 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74  ed in place.** t
12e30 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  he mutex routine
12e40 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
12e50 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ite.)^  ^SQLite 
12e60 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
12e70 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f  the.** content o
12e80 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
12e90 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
12ea0 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74  ructure before t
12eb0 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  he call to.** [s
12ec0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
12ed0 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51   returns. ^If SQ
12ee0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
12ef0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
12f00 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
12f10 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
12f20 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
12f30 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
12f40 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
12f50 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
12f60 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
12f70 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
12f80 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
12f90 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
12fa0 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
12fb0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
12fc0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12fd0 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
12fe0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
12ff0 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
13000 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13010 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  GETMUTEX]] <dt>S
13020 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
13030 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
13040 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
13050 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
13060 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
13070 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
13080 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
13090 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
130a0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
130b0 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20  ucture.  The.** 
130c0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
130d0 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
130e0 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
130f0 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
13100 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20  y defined mutex 
13110 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
13120 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
13130 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
13140 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
13150 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  utex allocation.
13160 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
13170 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20   a wrapper used 
13180 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75  to track mutex u
13190 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d  sage for perform
131a0 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e  ance.** profilin
131b0 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f  g or testing, fo
131c0 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66  r example.   ^If
131d0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
131e0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
131f0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
13200 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
13210 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
13220 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
13230 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65  en.** the entire
13240 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73   mutexing subsys
13250 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66  tem is omitted f
13260 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e  rom the build an
13270 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f  d hence calls to
13280 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
13290 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20  fig()] with the 
132a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
132b0 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  TMUTEX configura
132c0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
132d0 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
132e0 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
132f0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13300 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
13310 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13320 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
13330 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
13340 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
13350 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  wo arguments tha
13360 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
13370 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72  default.** memor
13380 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  y allocation for
13390 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   the lookaside m
133a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
133b0 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61  on each.** [data
133c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
133d0 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67  .  The first arg
133e0 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
133f0 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
13400 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
13410 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ot and the secon
13420 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
13430 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f  of.** slots allo
13440 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61  cated to each da
13450 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13460 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74  n.)^  ^(This opt
13470 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
13480 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c  <i>default</i> l
13490 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54  ookaside size. T
134a0 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  he [SQLITE_DBCON
134b0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a  FIG_LOOKASIDE].*
134c0 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74  * verb to [sqlit
134d0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
134e0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
134f0 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
13500 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ide.** configura
13510 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
13520 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29  al connections.)
13530 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
13540 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
13550 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
13560 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
13570 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
13580 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
13590 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
135a0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
135b0 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e  pointer to.** an
135c0 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
135d0 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
135e0 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
135f0 73 70 65 63 69 66 69 65 73 20 74 68 65 20 69 6e  specifies the in
13600 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20  terface.** to a 
13610 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
13620 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
13630 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b  .)^  ^SQLite mak
13640 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
13650 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75  .** object and u
13660 73 65 73 20 69 74 20 66 6f 72 20 70 61 67 65 20  ses it for page 
13670 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  cache memory all
13680 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a  ocations.</dd>.*
13690 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
136a0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d  NFIG_GETPCACHE2]
136b0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
136c0 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f  FIG_GETPCACHE2</
136d0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
136e0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
136f0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
13700 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
13710 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73  nter to an.** [s
13720 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
13730 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20  thods2] object. 
13740 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f   SQLite copies o
13750 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
13760 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
13770 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20  ementation into 
13780 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c  that object.)^ <
13790 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
137a0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d  ITE_CONFIG_LOG]]
137b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
137c0 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  IG_LOG</dt>.** <
137d0 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43  dd> The SQLITE_C
137e0 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e  ONFIG_LOG option
137f0 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66   is used to conf
13800 69 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 65  igure the SQLite
13810 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f  .** global [erro
13820 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65  r log]..** (^The
13830 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
13840 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OG option takes 
13850 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61  two arguments: a
13860 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a   pointer to a.**
13870 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
13880 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20   call signature 
13890 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  of void(*)(void*
138a0 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
138b0 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69  ), .** and a poi
138c0 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49  nter to void. ^I
138d0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70  f the function p
138e0 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
138f0 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76  LL, it is.** inv
13900 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oked by [sqlite3
13910 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65  _log()] to proce
13920 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20  ss each logging 
13930 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
13940 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  ** function poin
13950 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ter is NULL, the
13960 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
13970 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d   interface becom
13980 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e  es a no-op..** ^
13990 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72  The void pointer
139a0 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63   that is the sec
139b0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
139c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
139d0 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74  G is.** passed t
139e0 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69  hrough as the fi
139f0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
13a00 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
13a10 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
13a20 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e  ** function when
13a30 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69  ever that functi
13a40 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  on is invoked.  
13a50 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
13a60 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
13a70 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20  logger function 
13a80 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
13a90 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
13aa0 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f   to the correspo
13ab0 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  nding.** [sqlite
13ac0 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e  3_log()] call an
13ad0 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f  d is intended to
13ae0 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f   be a [result co
13af0 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78  de] or an.** [ex
13b00 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
13b10 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64  de].  ^The third
13b20 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65   parameter passe
13b30 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20  d to the logger 
13b40 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67  is.** log messag
13b50 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69  e after formatti
13b60 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f  ng via [sqlite3_
13b70 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20  snprintf()]..** 
13b80 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69  The SQLite loggi
13b90 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ng interface is 
13ba0 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74  not reentrant; t
13bb0 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
13bc0 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62  on.** supplied b
13bd0 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
13be0 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b  n must not invok
13bf0 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
13c00 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20  erface..** In a 
13c10 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61  multi-threaded a
13c20 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20  pplication, the 
13c30 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
13c40 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75  ned logger.** fu
13c50 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74  nction must be t
13c60 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e  hreadsafe. </dd>
13c70 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13c80 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74  CONFIG_URI]] <dt
13c90 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  >SQLITE_CONFIG_U
13ca0 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 69 73  RI.** <dd>^(This
13cb0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
13cc0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
13cd0 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66 20  of type int. If 
13ce0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a  non-zero, then.*
13cf0 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  * URI handling i
13d00 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
13d10 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d  ed. If the param
13d20 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 68  eter is zero, th
13d30 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a  en URI handling.
13d40 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  ** is globally d
13d50 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55  isabled.)^ ^If U
13d60 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
13d70 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c  lobally enabled,
13d80 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a   all filenames.*
13d90 2a 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  * passed to [sql
13da0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
13db0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
13dc0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
13dd0 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63  16()] or.** spec
13de0 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66  ified as part of
13df0 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e   [ATTACH] comman
13e00 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  ds are interpret
13e10 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61  ed as URIs, rega
13e20 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65  rdless.** of whe
13e30 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
13e40 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
13e50 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68  ] flag is set wh
13e60 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  en the database.
13e70 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
13e80 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20   opened. ^If it 
13e90 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61  is globally disa
13ea0 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20  bled, filenames 
13eb0 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65  are.** only inte
13ec0 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20  rpreted as URIs 
13ed0 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50  if the SQLITE_OP
13ee0 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73  EN_URI flag is s
13ef0 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64  et when the.** d
13f00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13f10 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28  on is opened. ^(
13f20 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20  By default, URI 
13f30 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
13f40 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64  ally.** disabled
13f50 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61  . The default va
13f60 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67  lue may be chang
13f70 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20  ed by compiling 
13f80 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
13f90 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d  ITE_USE_URI] sym
13fa0 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a  bol defined.)^.*
13fb0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13fc0 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
13fd0 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53  DEX_SCAN]] <dt>S
13fe0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
13ff0 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
14000 0a 2a 2a 20 3c 64 64 3e 5e 54 68 69 73 20 6f 70  .** <dd>^This op
14010 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
14020 67 6c 65 20 69 6e 74 65 67 65 72 20 61 72 67 75  gle integer argu
14030 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e  ment which is in
14040 74 65 72 70 72 65 74 65 64 20 61 73 0a 2a 2a 20  terpreted as.** 
14050 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64  a boolean in ord
14060 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  er to enable or 
14070 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20  disable the use 
14080 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69  of covering indi
14090 63 65 73 20 66 6f 72 0a 2a 2a 20 66 75 6c 6c 20  ces for.** full 
140a0 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74  table scans in t
140b0 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a  he query optimiz
140c0 65 72 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c  er.  ^The defaul
140d0 74 20 73 65 74 74 69 6e 67 20 69 73 20 64 65 74  t setting is det
140e0 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68  ermined.** by th
140f0 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f  e [SQLITE_ALLOW_
14100 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
14110 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  CAN] compile-tim
14120 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20  e option, or is 
14130 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20  "on".** if that 
14140 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
14150 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a  ion is omitted..
14160 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20 74  ** The ability t
14170 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73  o disable the us
14180 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e  e of covering in
14190 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74  dices for full t
141a0 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73  able scans.** is
141b0 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e   because some in
141c0 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20  correctly coded 
141d0 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61 74 69  legacy applicati
141e0 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e  ons might malfun
141f0 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68  ction.** when th
14200 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69  e optimization i
14210 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76  s enabled.  Prov
14220 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74  iding the abilit
14230 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20  y to.** disable 
14240 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  the optimization
14250 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65   allows the olde
14260 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63 61  r, buggy applica
14270 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72  tion code to wor
14280 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61  k.** without cha
14290 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65  nge even with ne
142a0 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
142b0 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  SQLite..**.** [[
142c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
142d0 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f  ACHE]] [[SQLITE_
142e0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
142f0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
14300 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61  _CONFIG_PCACHE a
14310 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  nd SQLITE_CONFIG
14320 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64  _GETPCACHE.** <d
14330 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73  d> These options
14340 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e   are obsolete an
14350 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  d should not be 
14360 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65  used by new code
14370 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65  ..** They are re
14380 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77  tained for backw
14390 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
143a0 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e  ty but are now n
143b0 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  o-ops..** </dd>.
143c0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
143d0 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a  ONFIG_SQLLOG]].*
143e0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
143f0 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64  FIG_SQLLOG.** <d
14400 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  d>This option is
14410 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
14420 69 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d  if sqlite is com
14430 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
14440 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
14450 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f  _SQLLOG] pre-pro
14460 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66  cessor macro def
14470 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74 20  ined. The first 
14480 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a  argument should.
14490 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ** be a pointer 
144a0 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66  to a function of
144b0 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f   type void(*)(vo
144c0 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e  id*,sqlite3*,con
144d0 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a  st char*, int)..
144e0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68  ** The second sh
144f0 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20  ould be of type 
14500 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c  (void*). The cal
14510 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
14520 20 62 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a   by the library.
14530 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70 61  ** in three sepa
14540 72 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63  rate circumstanc
14550 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62  es, identified b
14560 79 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73  y the value pass
14570 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75  ed as the.** fou
14580 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49  rth parameter. I
14590 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
145a0 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68 65  ameter is 0, the
145b0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
145c0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73  onnection.** pas
145d0 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
145e0 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a  d argument has j
145f0 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e  ust been opened.
14600 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
14610 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ent.** points to
14620 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69   a buffer contai
14630 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66  ning the name of
14640 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61   the main databa
14650 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a  se file. If the.
14660 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
14670 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74  ter is 1, then t
14680 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
14690 20 74 68 61 74 20 74 68 65 20 74 68 69 72 64 20   that the third 
146a0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69  parameter.** poi
146b0 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20  nts to has just 
146c0 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f  been executed. O
146d0 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74 68  r, if the fourth
146e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c   parameter is 2,
146f0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e   then.** the con
14700 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61  nection being pa
14710 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
14720 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
14730 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68  being closed. Th
14740 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
14750 65 74 65 72 20 69 73 20 70 61 73 73 65 64 20 4e  eter is passed N
14760 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65  ULL In this case
14770 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66  .  An example of
14780 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63   using this.** c
14790 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
147a0 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20  ion can be seen 
147b0 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c  in the "test_sql
147c0 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69  log.c" source fi
147d0 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e  le in.** the can
147e0 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f  onical SQLite so
147f0 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a  urce tree.</dd>.
14800 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14810 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d  ONFIG_MMAP_SIZE]
14820 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
14830 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
14840 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f  .** <dd>^SQLITE_
14850 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
14860 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69   takes two 64-bi
14870 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74  t integer (sqlit
14880 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73  e3_int64) values
14890 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68 65  .** that are the
148a0 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69   default mmap si
148b0 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65  ze limit (the de
148c0 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f  fault setting fo
148d0 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61  r.** [PRAGMA mma
148e0 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65  p_size]) and the
148f0 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64   maximum allowed
14900 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74   mmap size limit
14910 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
14920 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65  t setting can be
14930 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 65   overridden by e
14940 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
14950 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  nection using.**
14960 20 65 69 74 68 65 72 20 74 68 65 20 5b 50 52 41   either the [PRA
14970 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63  GMA mmap_size] c
14980 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73  ommand, or by us
14990 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ing the.** [SQLI
149a0 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
149b0 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  ZE] file control
149c0 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d  .  ^(The maximum
149d0 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69   allowed mmap si
149e0 7a 65 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20  ze.** cannot be 
149f0 63 68 61 6e 67 65 64 20 61 74 20 72 75 6e 2d 74  changed at run-t
14a00 69 6d 65 2e 20 20 4e 6f 72 20 6d 61 79 20 74 68  ime.  Nor may th
14a10 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65  e maximum allowe
14a20 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 65  d mmap size.** e
14a30 78 63 65 65 64 20 74 68 65 20 63 6f 6d 70 69 6c  xceed the compil
14a40 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d  e-time maximum m
14a50 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20  map size set by 
14a60 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  the.** [SQLITE_M
14a70 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f  AX_MMAP_SIZE] co
14a80 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
14a90 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68  n.)^.** ^If eith
14aa0 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  er argument to t
14ab0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65  his option is ne
14ac0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61  gative, then tha
14ad0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  t argument is.**
14ae0 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20   changed to its 
14af0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66  compile-time def
14b00 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ault..**.** [[SQ
14b10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
14b20 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20  2_HEAPSIZE]].** 
14b30 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14b40 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
14b50 0a 2a 2a 20 3c 64 64 3e 5e 54 68 69 73 20 6f 70  .** <dd>^This op
14b60 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61  tion is only ava
14b70 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65  ilable if SQLite
14b80 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72   is compiled for
14b90 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 77 69 74 68   Windows.** with
14ba0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e   the [SQLITE_WIN
14bb0 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70  32_MALLOC] pre-p
14bc0 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64  rocessor macro d
14bd0 65 66 69 6e 65 64 2e 0a 2a 2a 20 53 51 4c 49 54  efined..** SQLIT
14be0 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
14bf0 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20  EAPSIZE takes a 
14c00 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20  32-bit unsigned 
14c10 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a  integer value.**
14c20 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20   that specifies 
14c30 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  the maximum size
14c40 20 6f 66 20 74 68 65 20 68 65 61 70 2e 0a 2a 2a   of the heap..**
14c50 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
14c60 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14c70 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20  SINGLETHREAD  1 
14c80 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
14c90 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
14ca0 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32  _MULTITHREAD   2
14cb0 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
14cc0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
14cd0 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20  G_SERIALIZED    
14ce0 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  3  /* nil */.#de
14cf0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
14d00 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20  IG_MALLOC       
14d10 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   4  /* sqlite3_m
14d20 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
14d30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
14d40 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20  NFIG_GETMALLOC  
14d50 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33     5  /* sqlite3
14d60 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
14d70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14d80 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20  CONFIG_SCRATCH  
14d90 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a       6  /* void*
14da0 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
14db0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14dc0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
14dd0 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69  HE     7  /* voi
14de0 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
14df0 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
14e00 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
14e10 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76           8  /* v
14e20 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  oid*, int nByte,
14e30 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66   int min */.#def
14e40 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
14e50 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20  G_MEMSTATUS     
14e60 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f  9  /* boolean */
14e70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14e80 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20  CONFIG_MUTEX    
14e90 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74      10  /* sqlit
14ea0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
14eb0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
14ec0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
14ed0 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73  TEX     11  /* s
14ee0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
14ef0 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76  hods* */./* prev
14f00 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f  iously SQLITE_CO
14f10 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20  NFIG_CHUNKALLOC 
14f20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20  12 which is now 
14f30 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66  unused. */ .#def
14f40 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
14f50 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31  G_LOOKASIDE    1
14f60 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  3  /* int int */
14f70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14f80 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20  CONFIG_PCACHE   
14f90 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70      14  /* no-op
14fa0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
14fb0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
14fc0 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f  CHE    15  /* no
14fd0 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  -op */.#define S
14fe0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
14ff0 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a            16  /*
15000 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f   xFunc, void* */
15010 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15020 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20  CONFIG_URI      
15030 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a      17  /* int *
15040 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15050 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20  _CONFIG_PCACHE2 
15060 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69       18  /* sqli
15070 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
15080 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ds2* */.#define 
15090 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
150a0 54 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f  TPCACHE2   19  /
150b0 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
150c0 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64  _methods2* */.#d
150d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
150e0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
150f0 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69  EX_SCAN 20  /* i
15100 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
15110 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
15120 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20  OG       21  /* 
15130 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a  xSqllog, void* *
15140 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15150 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
15160 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69  E    22  /* sqli
15170 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74  te3_int64, sqlit
15180 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66  e3_int64 */.#def
15190 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
151a0 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
151b0 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74        23  /* int
151c0 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   nByte */../*.**
151d0 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
151e0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43  ase Connection C
151f0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
15200 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
15210 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
15220 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
15230 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
15240 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
15250 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
15260 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
15270 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
15280 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
15290 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
152a0 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
152b0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
152c0 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
152d0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
152e0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
152f0 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
15300 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
15310 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
15320 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
15330 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
15340 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
15350 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
15360 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  db_config()] to 
15370 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
15380 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
15390 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  d.  ^The [sqlite
153a0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
153b0 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
153c0 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
153d0 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
153e0 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
153f0 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
15400 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
15410 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
15420 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
15430 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
15440 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
15450 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
15460 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
15470 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61   three additiona
15480 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  l arguments that
15490 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a   determine the .
154a0 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  ** [lookaside me
154b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20  mory allocator] 
154c0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
154d0 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  r the [database 
154e0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
154f0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
15500 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70  ent (the third p
15510 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
15520 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
15530 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  ] is a.** pointe
15540 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75  r to a memory bu
15550 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20  ffer to use for 
15560 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
15570 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
15580 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74  argument after t
15590 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  he SQLITE_DBCONF
155a0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72  IG_LOOKASIDE ver
155b0 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c  b.** may be NULL
155c0 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53   in which case S
155d0 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63  QLite will alloc
155e0 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61  ate the.** looka
155f0 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65  side buffer itse
15600 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  lf using [sqlite
15610 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68  3_malloc()]. ^Th
15620 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
15630 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
15640 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
15650 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20  de buffer slot. 
15660 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
15670 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62  ment is the numb
15680 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20  er of.** slots. 
15690 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
156a0 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66   buffer in the f
156b0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
156c0 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68  st be greater th
156d0 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74  an.** or equal t
156e0 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66  o the product of
156f0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
15700 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e  third arguments.
15710 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20    The buffer.** 
15720 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20  must be aligned 
15730 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75  to an 8-byte bou
15740 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20  ndary.  ^If the 
15750 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
15760 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43  to.** SQLITE_DBC
15770 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
15780 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c  is not a multipl
15790 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e  e of 8, it is in
157a0 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e  ternally.** roun
157b0 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20  ded down to the 
157c0 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c  next smaller mul
157d0 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54  tiple of 8.  ^(T
157e0 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
157f0 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ory.** configura
15800 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62  tion for a datab
15810 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
15820 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67  an only be chang
15830 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20  ed when that.** 
15840 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f  connection is no
15850 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e  t currently usin
15860 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  g lookaside memo
15870 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20  ry, or in other 
15880 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68  words.** when th
15890 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65  e "current value
158a0 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  " returned by.**
158b0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61   [sqlite3_db_sta
158c0 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43  tus](D,[SQLITE_C
158d0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
158e0 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a  ,...) is zero..*
158f0 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
15900 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
15910 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e  aside memory con
15920 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20  figuration when 
15930 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d  lookaside.** mem
15940 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65  ory is in use le
15950 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75  aves the configu
15960 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64  ration unchanged
15970 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a   and returns .**
15980 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29   [SQLITE_BUSY].)
15990 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  ^</dd>.**.** <dt
159a0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
159b0 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74  _ENABLE_FKEY</dt
159c0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
159d0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
159e0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
159f0 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d  ble the enforcem
15a00 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69  ent of.** [forei
15a10 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e  gn key constrain
15a20 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75  ts].  There shou
15a30 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
15a40 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
15a50 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
15a60 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
15a70 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
15a80 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66  o disable FK enf
15a90 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73  orcement,.** pos
15aa0 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
15ab0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  FK enforcement o
15ac0 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
15ad0 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ave FK enforceme
15ae0 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e  nt.** unchanged.
15af0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
15b00 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
15b10 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
15b20 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
15b30 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
15b40 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
15b50 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65  ether FK enforce
15b60 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f  ment is off or o
15b70 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  n.** following t
15b80 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
15b90 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
15ba0 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  may be a NULL po
15bb0 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69  inter, in.** whi
15bc0 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 65  ch case the FK e
15bd0 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69  nforcement setti
15be0 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
15bf0 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
15c00 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
15c10 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
15c20 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20  TRIGGER</dt>.** 
15c30 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
15c40 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
15c50 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b  ble or disable [
15c60 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
15c70 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54   triggers]..** T
15c80 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
15c90 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
15ca0 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
15cb0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
15cc0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
15cd0 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
15ce0 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20  le triggers,.** 
15cf0 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
15d00 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e  le triggers or n
15d10 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
15d20 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63   the setting unc
15d30 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73  hanged..** The s
15d40 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
15d50 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
15d60 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
15d70 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
15d80 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
15d90 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74  dicate whether t
15da0 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61  riggers are disa
15db0 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a  bled or enabled.
15dc0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
15dd0 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
15de0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
15df0 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
15e00 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
15e10 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65   case the trigge
15e20 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  r setting is not
15e30 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
15e40 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c  </dd>.**.** </dl
15e50 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
15e60 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
15e70 4b 41 53 49 44 45 20 20 20 20 20 20 20 31 30 30  KASIDE       100
15e80 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20  1  /* void* int 
15e90 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
15ea0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
15eb0 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31  NABLE_FKEY     1
15ec0 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  002  /* int int*
15ed0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15ee0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
15ef0 4c 45 5f 54 52 49 47 47 45 52 20 20 31 30 30 33  LE_TRIGGER  1003
15f00 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f    /* int int* */
15f10 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
15f20 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
15f30 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65  able Extended Re
15f40 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  sult Codes.**.**
15f50 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
15f60 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
15f70 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e  des() routine en
15f80 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
15f90 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64  s the.** [extend
15fa0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
15fb0 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69   feature of SQLi
15fc0 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65  te. ^The extende
15fd0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65  d result.** code
15fe0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
15ff0 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69  y default for hi
16000 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69  storical compati
16010 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73  bility..*/.int s
16020 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
16030 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c  result_codes(sql
16040 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66  ite3*, int onoff
16050 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
16060 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20  EF: Last Insert 
16070 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63  Rowid.**.** ^Eac
16080 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20  h entry in most 
16090 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65  SQLite tables (e
160a0 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f  xcept for [WITHO
160b0 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73  UT ROWID] tables
160c0 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75  ).** has a uniqu
160d0 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a  e 64-bit signed.
160e0 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63  ** integer key c
160f0 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44  alled the [ROWID
16100 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68   | "rowid"]. ^Th
16110 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79  e rowid is alway
16120 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61  s available.** a
16130 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20  s an undeclared 
16140 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57  column named ROW
16150 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57  ID, OID, or _ROW
16160 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ID_ as long as t
16170 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72  hose.** names ar
16180 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20  e not also used 
16190 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  by explicitly de
161a0 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20  clared columns. 
161b0 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65  ^If.** the table
161c0 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66   has a column of
161d0 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50   type [INTEGER P
161e0 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e  RIMARY KEY] then
161f0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20   that column.** 
16200 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73  is another alias
16210 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a   for the rowid..
16220 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
16230 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
16240 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61 63  owid(D) interfac
16250 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72  e returns the [r
16260 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a 2a  owid] of the .**
16270 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63   most recent suc
16280 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
16290 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74 61   into a rowid ta
162a0 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c 20  ble or [virtual 
162b0 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74  table].** on dat
162c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
162d0 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 20   D..** ^Inserts 
162e0 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f  into [WITHOUT RO
162f0 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20  WID] tables are 
16300 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a 2a  not recorded..**
16310 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66   ^If no successf
16320 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74  ul [INSERT]s int
16330 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 0a 2a  o rowid tables.*
16340 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75  * have ever occu
16350 72 72 65 64 20 6f 6e 20 74 68 65 20 64 61 74 61  rred on the data
16360 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
16370 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69  D, .** then sqli
16380 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
16390 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e 73  rowid(D) returns
163a0 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49   zero..**.** ^(I
163b0 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63  f an [INSERT] oc
163c0 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72  curs within a tr
163d0 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20  igger or within 
163e0 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  a [virtual table
163f0 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65  ].** method, the
16400 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  n this routine w
16410 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b  ill return the [
16420 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e  rowid] of the in
16430 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73  serted.** row as
16440 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
16450 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20  gger or virtual 
16460 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20  table method is 
16470 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20  running..** But 
16480 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72  once the trigger
16490 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c   or virtual tabl
164a0 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74  e method ends, t
164b0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
164c0 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f  d .** by this ro
164d0 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f  utine reverts to
164e0 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66   what it was bef
164f0 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ore the trigger 
16500 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61  or virtual.** ta
16510 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e  ble method began
16520 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49  .)^.**.** ^An [I
16530 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c  NSERT] that fail
16540 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74  s due to a const
16550 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20  raint violation 
16560 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63  is not a.** succ
16570 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
16580 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  and does not cha
16590 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65  nge the value re
165a0 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a  turned by this.*
165b0 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75  * routine.  ^Thu
165c0 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c  s INSERT OR FAIL
165d0 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f  , INSERT OR IGNO
165e0 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f  RE, INSERT OR RO
165f0 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49  LLBACK,.** and I
16600 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d  NSERT OR ABORT m
16610 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74  ake no changes t
16620 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  o the return val
16630 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f  ue of this.** ro
16640 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72  utine when their
16650 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73   insertion fails
16660 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54  .  ^(When INSERT
16670 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65   OR REPLACE.** e
16680 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73  ncounters a cons
16690 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
166a0 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61  , it does not fa
166b0 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45  il.  The.** INSE
166c0 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20  RT continues to 
166d0 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72  completion after
166e0 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74   deleting rows t
166f0 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68  hat caused.** th
16700 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f  e constraint pro
16710 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f  blem so INSERT O
16720 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61  R REPLACE will a
16730 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20  lways change.** 
16740 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
16750 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
16760 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72  ce.)^.**.** ^For
16770 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
16780 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61   this routine, a
16790 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f  n [INSERT] is co
167a0 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62  nsidered to.** b
167b0 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65  e successful eve
167c0 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65  n if it is subse
167d0 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62  quently rolled b
167e0 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ack..**.** This 
167f0 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65  function is acce
16800 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74  ssible to SQL st
16810 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65  atements via the
16820 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74  .** [last_insert
16830 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e  _rowid() SQL fun
16840 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
16850 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
16860 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65  ad performs a ne
16870 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68  w [INSERT] on th
16880 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61  e same.** databa
16890 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68  se connection wh
168a0 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ile the [sqlite3
168b0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
168c0 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f  id()].** functio
168d0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64  n is running and
168e0 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68   thus changes th
168f0 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  e last insert [r
16900 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  owid],.** then t
16910 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
16920 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61  d by [sqlite3_la
16930 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
16940 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69  )] is.** unpredi
16950 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74  ctable and might
16960 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65   not equal eithe
16970 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65  r the old or the
16980 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73   new.** last ins
16990 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a  ert [rowid]..*/.
169a0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
169b0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
169c0 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a  t_rowid(sqlite3*
169d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
169e0 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75  EF: Count The Nu
169f0 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
16a00 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  ified.**.** ^Thi
16a10 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
16a20 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
16a30 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74   database rows t
16a40 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 64  hat were changed
16a50 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20  .** or inserted 
16a60 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 68  or deleted by th
16a70 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
16a80 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74  completed SQL st
16a90 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68  atement.** on th
16aa0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
16ab0 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
16ac0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70  d by the first p
16ad0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f  arameter..** ^(O
16ae0 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 74  nly changes that
16af0 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70   are directly sp
16b00 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 5b  ecified by the [
16b10 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45  INSERT], [UPDATE
16b20 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45  ],.** or [DELETE
16b30 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20  ] statement are 
16b40 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69  counted.  Auxili
16b50 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73  ary changes caus
16b60 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72  ed by.** trigger
16b70 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65  s or [foreign ke
16b80 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e  y actions] are n
16b90 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73  ot counted.)^ Us
16ba0 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
16bb0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
16bc0 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66  )] function to f
16bd0 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75  ind the total nu
16be0 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a  mber of changes.
16bf0 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61  ** including cha
16c00 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74  nges caused by t
16c10 72 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65  riggers and fore
16c20 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e  ign key actions.
16c30 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20  .**.** ^Changes 
16c40 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61  to a view that a
16c50 72 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20  re simulated by 
16c60 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74  an [INSTEAD OF t
16c70 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e  rigger].** are n
16c80 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c  ot counted.  Onl
16c90 79 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61  y real table cha
16ca0 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64  nges are counted
16cb0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77  ..**.** ^(A "row
16cc0 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63 68   change" is a ch
16cd0 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65  ange to a single
16ce0 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65   row of a single
16cf0 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64   table.** caused
16d00 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44   by an INSERT, D
16d10 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45  ELETE, or UPDATE
16d20 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77   statement.  Row
16d30 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68  s that.** are ch
16d40 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65 66  anged as side ef
16d50 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43  fects of [REPLAC
16d60 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65  E] constraint re
16d70 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c  solution,.** rol
16d80 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f  lback, ABORT pro
16d90 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54  cessing, [DROP T
16da0 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79  ABLE], or by any
16db0 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e   other.** mechan
16dc0 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e  isms do not coun
16dd0 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77 20  t as direct row 
16de0 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a  changes.)^.**.**
16df0 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74   A "trigger cont
16e00 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20  ext" is a scope 
16e10 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61  of execution tha
16e20 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20  t begins and.** 
16e30 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63  ends with the sc
16e40 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54  ript of a [CREAT
16e50 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
16e60 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53  ger]. .** Most S
16e70 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
16e80 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f  e.** evaluated o
16e90 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72  utside of any tr
16ea0 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 20  igger.  This is 
16eb0 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a  the "top level".
16ec0 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ** trigger conte
16ed0 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 65  xt.  If a trigge
16ee0 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65  r fires from the
16ef0 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a   top level, a.**
16f00 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e   new trigger con
16f10 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 20  text is entered 
16f20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e  for the duration
16f30 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20   of that one.** 
16f40 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 69  trigger.  Subtri
16f50 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75 62  ggers create sub
16f60 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65  contexts for the
16f70 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a  ir duration..**.
16f80 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c  ** ^Calling [sql
16f90 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20  ite3_exec()] or 
16fa0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
16fb0 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65   recursively doe
16fc0 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20  s.** not create 
16fd0 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f  a new trigger co
16fe0 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ntext..**.** ^Th
16ff0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
17000 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
17010 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61  f direct row cha
17020 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d  nges in the.** m
17030 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
17040 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
17050 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77  LETE statement w
17060 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a  ithin the same.*
17070 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  * trigger contex
17080 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20  t..**.** ^Thus, 
17090 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d  when called from
170a0 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20   the top level, 
170b0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  this function re
170c0 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  turns the.** num
170d0 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69  ber of changes i
170e0 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
170f0 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
17100 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74  , or DELETE.** t
17110 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65  hat also occurre
17120 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76  d at the top lev
17130 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68  el.  ^(Within th
17140 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67  e body of a trig
17150 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69  ger,.** the sqli
17160 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e  te3_changes() in
17170 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 63  terface can be c
17180 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68  alled to find th
17190 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63  e number of.** c
171a0 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f  hanges in the mo
171b0 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
171c0 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50  leted INSERT, UP
171d0 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
171e0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  ** statement wit
171f0 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20  hin the body of 
17200 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72  the same trigger
17210 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
17220 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65  e number returne
17230 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  d does not inclu
17240 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61  de changes.** ca
17250 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67  used by subtrigg
17260 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20  ers since those 
17270 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63  have their own c
17280 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ontext.)^.**.** 
17290 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
172a0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
172b0 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
172c0 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
172d0 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
172e0 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65   and the [change
172f0 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
17300 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
17310 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
17320 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
17330 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
17340 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
17350 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68  hile [sqlite3_ch
17360 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
17370 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
17380 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69  ue returned.** i
17390 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
173a0 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
173b0 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
173c0 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  e3_changes(sqlit
173d0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
173e0 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d  I3REF: Total Num
173f0 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
17400 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  fied.**.** ^This
17410 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
17420 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
17430 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73  row changes caus
17440 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a  ed by [INSERT],.
17450 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b  ** [UPDATE] or [
17460 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e  DELETE] statemen
17470 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61  ts since the [da
17480 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17490 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a  n] was opened..*
174a0 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 65  * ^(The count re
174b0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
174c0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
174d0 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63  ) includes all c
174e0 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61  hanges.** from a
174f0 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49 47 47  ll [CREATE TRIGG
17500 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f  ER | trigger] co
17510 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67  ntexts and chang
17520 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66  es made by.** [f
17530 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
17540 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ns]. However,.**
17550 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20   the count does 
17560 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e  not include chan
17570 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  ges used to impl
17580 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20  ement [REPLACE] 
17590 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20  constraints,.** 
175a0 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20  do rollbacks or 
175b0 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
175c0 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45  , or [DROP TABLE
175d0 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54  ] processing.  T
175e0 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73  he.** count does
175f0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77   not include row
17600 73 20 6f 66 20 76 69 65 77 73 20 74 68 61 74 20  s of views that 
17610 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44  fire an [INSTEAD
17620 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a   OF trigger],.**
17630 20 74 68 6f 75 67 68 20 69 66 20 74 68 65 20 49   though if the I
17640 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
17650 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  r makes changes 
17660 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73  of its own, thos
17670 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72  e changes .** ar
17680 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20  e counted.)^.** 
17690 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 6f 74  ^The sqlite3_tot
176a0 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e  al_changes() fun
176b0 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65  ction counts the
176c0 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e   changes as soon
176d0 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 65   as.** the state
176e0 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20  ment that makes 
176f0 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65  them is complete
17700 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 74  d (when the stat
17710 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20  ement handle.** 
17720 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71  is passed to [sq
17730 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
17740 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
17750 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53  ize()])..**.** S
17760 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
17770 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
17780 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
17790 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
177a0 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
177b0 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e [total_changes
177c0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
177d0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
177e0 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
177f0 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
17800 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
17810 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
17820 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  ile [sqlite3_tot
17830 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  al_changes()] is
17840 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
17850 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
17860 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74  ned is unpredict
17870 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
17880 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  ningful..*/.int 
17890 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
178a0 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
178b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
178c0 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f  : Interrupt A Lo
178d0 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79  ng-Running Query
178e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
178f0 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79  ction causes any
17900 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73   pending databas
17910 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61  e operation to a
17920 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75  bort and.** retu
17930 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65  rn at its earlie
17940 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20  st opportunity. 
17950 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  This routine is 
17960 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c  typically.** cal
17970 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20  led in response 
17980 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e  to a user action
17990 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e   such as pressin
179a0 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72  g "Cancel".** or
179b0 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68   Ctrl-C where th
179c0 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c  e user wants a l
179d0 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74  ong query operat
179e0 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69  ion to halt.** i
179f0 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  mmediately..**.*
17a00 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f  * ^It is safe to
17a10 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
17a20 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64  ne from a thread
17a30 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
17a40 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68  the.** thread th
17a50 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  at is currently 
17a60 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61  running the data
17a70 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20  base operation. 
17a80 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f   But it.** is no
17a90 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  t safe to call t
17aa0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
17ab0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
17ac0 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a  nection] that.**
17ad0 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69   is closed or mi
17ae0 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65  ght close before
17af0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
17b00 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  pt() returns..**
17b10 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f  .** ^If an SQL o
17b20 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79  peration is very
17b30 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64   nearly finished
17b40 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65   at the time whe
17b50 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74  n.** sqlite3_int
17b60 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c  errupt() is call
17b70 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68  ed, then it migh
17b80 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70  t not have an op
17b90 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20  portunity.** to 
17ba0 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  be interrupted a
17bb0 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75  nd might continu
17bc0 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e  e to completion.
17bd0 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f  .**.** ^An SQL o
17be0 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73  peration that is
17bf0 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c   interrupted wil
17c00 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
17c10 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20  _INTERRUPT]..** 
17c20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70  ^If the interrup
17c30 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ted SQL operatio
17c40 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20  n is an INSERT, 
17c50 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
17c60 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73  E.** that is ins
17c70 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20  ide an explicit 
17c80 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
17c90 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61  n the entire tra
17ca0 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c  nsaction.** will
17cb0 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
17cc0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a  automatically..*
17cd0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
17ce0 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63  3_interrupt(D) c
17cf0 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74  all is in effect
17d00 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65   until all curre
17d10 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  ntly running.** 
17d20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  SQL statements o
17d30 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
17d40 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65  ection] D comple
17d50 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51  te.  ^Any new SQ
17d60 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
17d70 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
17d80 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74   after the sqlit
17d90 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
17da0 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74  all and before t
17db0 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73  he .** running s
17dc0 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65  tatements reache
17dd0 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72  s zero are inter
17de0 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65  rupted as if the
17df0 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75  y had been.** ru
17e00 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74  nning prior to t
17e10 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
17e20 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e  rupt() call.  ^N
17e30 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ew SQL statement
17e40 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
17e50 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
17e60 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
17e70 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20  t count reaches 
17e80 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20  zero are.** not 
17e90 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20  effected by the 
17ea0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
17eb0 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  t()..** ^A call 
17ec0 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  to sqlite3_inter
17ed0 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63  rupt(D) that occ
17ee0 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61  urs when there a
17ef0 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a  re no running.**
17f00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
17f10 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68  is a no-op and h
17f20 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20  as no effect on 
17f30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
17f40 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
17f50 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
17f60 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
17f70 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a   call returns..*
17f80 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61  *.** If the data
17f90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
17fa0 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71  closes while [sq
17fb0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
17fc0 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67  )].** is running
17fd0 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73   then bad things
17fe0 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70   will likely hap
17ff0 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  pen..*/.void sql
18000 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73  ite3_interrupt(s
18010 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
18020 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
18030 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
18040 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70  tatement Is Comp
18050 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  lete.**.** These
18060 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
18070 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d  eful during comm
18080 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74  and-line input t
18090 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74  o determine if t
180a0 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  he.** currently 
180b0 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65  entered text see
180c0 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d  ms to form a com
180d0 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d  plete SQL statem
180e0 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64  ent or.** if add
180f0 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73  itional input is
18100 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73   needed before s
18110 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20  ending the text 
18120 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66  into.** SQLite f
18130 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68  or parsing.  ^Th
18140 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
18150 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70  urn 1 if the inp
18160 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70  ut string.** app
18170 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d  ears to be a com
18180 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d  plete SQL statem
18190 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65  ent.  ^A stateme
181a0 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20  nt is judged to 
181b0 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69  be.** complete i
181c0 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61  f it ends with a
181d0 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e   semicolon token
181e0 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72   and is not a pr
181f0 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c  efix of a.** wel
18200 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20  l-formed CREATE 
18210 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e  TRIGGER statemen
18220 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20  t.  ^Semicolons 
18230 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65  that are embedde
18240 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69  d within.** stri
18250 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71  ng literals or q
18260 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72  uoted identifier
18270 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e   names or commen
18280 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e  ts are not.** in
18290 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73  dependent tokens
182a0 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20   (they are part 
182b0 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20  of the token in 
182c0 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a  which they are.*
182d0 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20  * embedded) and 
182e0 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e  thus do not coun
182f0 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74  t as a statement
18300 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57   terminator.  ^W
18310 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64  hitespace.** and
18320 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66   comments that f
18330 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20  ollow the final 
18340 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67  semicolon are ig
18350 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  nored..**.** ^Th
18360 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
18370 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61  urn 0 if the sta
18380 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70  tement is incomp
18390 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20  lete.  ^If a.** 
183a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
183b0 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51  n fails, then SQ
183c0 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65  LITE_NOMEM is re
183d0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
183e0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f  hese routines do
183f0 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53   not parse the S
18400 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  QL statements th
18410 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64  us.** will not d
18420 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61  etect syntactica
18430 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51  lly incorrect SQ
18440 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51  L..**.** ^(If SQ
18450 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65  Lite has not bee
18460 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73  n initialized us
18470 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  ing [sqlite3_ini
18480 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72  tialize()] prior
18490 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67   .** to invoking
184a0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
184b0 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74  e16() then sqlit
184c0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
184d0 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75  is invoked.** au
184e0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73  tomatically by s
184f0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
18500 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e  6().  If that in
18510 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69  itialization fai
18520 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ls,.** then the 
18530 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
18540 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  m sqlite3_comple
18550 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e  te16() will be n
18560 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72  on-zero.** regar
18570 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
18580 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75   or not the inpu
18590 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74  t SQL is complet
185a0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  e.)^.**.** The i
185b0 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
185c0 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73  _complete()] mus
185d0 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
185e0 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20  inated.** UTF-8 
185f0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  string..**.** Th
18600 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
18610 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
18620 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ] must be a zero
18630 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
18640 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20  TF-16 string in 
18650 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
18660 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
18670 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74  3_complete(const
18680 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74   char *sql);.int
18690 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
186a0 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a  e16(const void *
186b0 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  sql);../*.** CAP
186c0 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20  I3REF: Register 
186d0 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61  A Callback To Ha
186e0 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59  ndle SQLITE_BUSY
186f0 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54   Errors.**.** ^T
18700 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
18710 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
18720 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20  tion that might 
18730 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
18740 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70  ver.** an attemp
18750 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  t is made to ope
18760 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
18770 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20  le that another 
18780 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f  thread.** or pro
18790 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e  cess has locked.
187a0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62  .**.** ^If the b
187b0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
187c0 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49  NULL, then [SQLI
187d0 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c  TE_BUSY] or [SQL
187e0 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
187f0 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  D].** is returne
18800 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70  d immediately up
18810 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  on encountering 
18820 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74  the lock.  ^If t
18830 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
18840 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  .** is not NULL,
18850 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   then the callba
18860 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  ck might be invo
18870 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67  ked with two arg
18880 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  uments..**.** ^T
18890 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
188a0 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61  t to the busy ha
188b0 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20  ndler is a copy 
188c0 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69  of the void* poi
188d0 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  nter which.** is
188e0 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
188f0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
18900 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20  usy_handler().  
18910 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
18920 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62  ment to.** the b
18930 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy handler call
18940 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62  back is the numb
18950 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74  er of times that
18960 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
18970 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e  r has.** been in
18980 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c  voked for this l
18990 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e  ocking event.  ^
189a0 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63  If the.** busy c
189b0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
189c0 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74  0, then no addit
189d0 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61  ional attempts a
189e0 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63  re made to.** ac
189f0 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
18a00 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55  e and [SQLITE_BU
18a10 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  SY] or [SQLITE_I
18a20 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73  OERR_BLOCKED] is
18a30 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49   returned..** ^I
18a40 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  f the callback r
18a50 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
18a60 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74   then another at
18a70 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65  tempt.** is made
18a80 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74   to open the dat
18a90 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e  abase for readin
18aa0 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20  g and the cycle 
18ab0 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  repeats..**.** T
18ac0 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61  he presence of a
18ad0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f   busy handler do
18ae0 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  es not guarantee
18af0 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65   that it will be
18b00 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e   invoked.** when
18b10 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63   there is lock c
18b20 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53  ontention. ^If S
18b30 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73  QLite determines
18b40 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74   that invoking t
18b50 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c  he busy.** handl
18b60 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20  er could result 
18b70 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69  in a deadlock, i
18b80 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20  t will go ahead 
18b90 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  and return [SQLI
18ba0 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b  TE_BUSY].** or [
18bb0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
18bc0 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66  CKED] instead of
18bd0 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75   invoking the bu
18be0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43  sy handler..** C
18bf0 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72  onsider a scenar
18c00 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f  io where one pro
18c10 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
18c20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74  a read lock that
18c30 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67  .** it is trying
18c40 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
18c50 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61   reserved lock a
18c60 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70  nd.** a second p
18c70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
18c80 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  g a reserved loc
18c90 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79  k that it is try
18ca0 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  ing.** to promot
18cb0 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76  e to an exclusiv
18cc0 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72  e lock.  The fir
18cd0 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  st process canno
18ce0 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63  t proceed.** bec
18cf0 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
18d00 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
18d10 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
18d20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a  process cannot.*
18d30 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73  * proceed becaus
18d40 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
18d50 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49  by the first.  I
18d60 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73  f both processes
18d70 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62  .** invoke the b
18d80 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65  usy handlers, ne
18d90 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20  ither will make 
18da0 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54  any progress.  T
18db0 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c  herefore,.** SQL
18dc0 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ite returns [SQL
18dd0 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68  ITE_BUSY] for th
18de0 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c  e first process,
18df0 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69   hoping that thi
18e00 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65  s.** will induce
18e10 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
18e20 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74  ss to release it
18e30 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20  s read lock and 
18e40 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63  allow.** the sec
18e50 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70  ond process to p
18e60 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  roceed..**.** ^T
18e70 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20  he default busy 
18e80 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
18e90 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ..**.** ^The [SQ
18ea0 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72  LITE_BUSY] error
18eb0 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   is converted to
18ec0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
18ed0 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20  LOCKED].** when 
18ee0 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65  SQLite is in the
18ef0 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72   middle of a lar
18f00 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77  ge transaction w
18f10 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20  here all the.** 
18f20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74  changes will not
18f30 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e   fit into the in
18f40 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20  -memory cache.  
18f50 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61  SQLite will.** a
18f60 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45  lready hold a RE
18f70 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74  SERVED lock on t
18f80 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
18f90 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a  , but it needs.*
18fa0 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69  * to promote thi
18fb0 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53  s lock to EXCLUS
18fc0 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63  IVE so that it c
18fd0 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a  an spill cache.*
18fe0 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65  * pages into the
18ff0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
19000 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63  ithout harm to c
19010 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61  oncurrent.** rea
19020 64 65 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73  ders.  ^If it is
19030 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f   unable to promo
19040 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65  te the lock, the
19050 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a  n the in-memory.
19060 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65  ** cache will be
19070 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f   left in an inco
19080 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 61  nsistent state a
19090 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a  nd so the error.
190a0 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f  ** code is promo
190b0 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c  ted from the rel
190c0 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b  atively benign [
190d0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a  SQLITE_BUSY] to.
190e0 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65  ** the more seve
190f0 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  re [SQLITE_IOERR
19100 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69  _BLOCKED].  ^Thi
19110 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f  s error code pro
19120 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73  motion.** forces
19130 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f   an automatic ro
19140 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68  llback of the ch
19150 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a  anges.  See the.
19160 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73  ** <a href="/cvs
19170 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72  trac/wiki?p=Corr
19180 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
19190 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f  usyError">.** Co
191a0 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e  rruptionFollowin
191b0 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77  gBusyError</a> w
191c0 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 64  iki page for a d
191d0 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79  iscussion of why
191e0 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f  .** this is impo
191f0 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  rtant..**.** ^(T
19200 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
19210 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
19220 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66  andler defined f
19230 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61  or each.** [data
19240 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
19250 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77  .  Setting a new
19260 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c   busy handler cl
19270 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76  ears any.** prev
19280 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c  iously set handl
19290 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61  er.)^  ^Note tha
192a0 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
192b0 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
192c0 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20  )].** will also 
192d0 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65  set or clear the
192e0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
192f0 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61  *.** The busy ca
19300 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f  llback should no
19310 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f  t take any actio
19320 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20  ns which modify 
19330 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
19340 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
19350 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
19360 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73   handler.  Any s
19370 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72  uch actions.** r
19380 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e  esult in undefin
19390 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20  ed behavior..** 
193a0 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c  .** A busy handl
193b0 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73  er must not clos
193c0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
193d0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20  onnection.** or 
193e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
193f0 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65  ent] that invoke
19400 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
19410 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
19420 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
19430 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
19440 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69  (void*,int), voi
19450 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
19460 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79  3REF: Set A Busy
19470 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e   Timeout.**.** ^
19480 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
19490 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  s a [sqlite3_bus
194a0 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79  y_handler | busy
194b0 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73   handler] that s
194c0 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73  leeps.** for a s
194d0 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20  pecified amount 
194e0 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74  of time when a t
194f0 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20  able is locked. 
19500 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a   ^The handler.**
19510 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74   will sleep mult
19520 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c  iple times until
19530 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
19540 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
19550 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20  leeping.** have 
19560 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41  accumulated.  ^A
19570 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d  fter at least "m
19580 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
19590 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20  of sleeping,.** 
195a0 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75  the handler retu
195b0 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73  rns 0 which caus
195c0 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  es [sqlite3_step
195d0 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ()] to return.**
195e0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
195f0 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
19600 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20  BLOCKED]..**.** 
19610 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f  ^Calling this ro
19620 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72  utine with an ar
19630 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e  gument less than
19640 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
19650 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61  o.** turns off a
19660 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  ll busy handlers
19670 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
19680 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
19690 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
196a0 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  r for a particul
196b0 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
196c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20  connection] any 
196d0 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74  any given moment
196e0 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75  .  If another bu
196f0 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61  sy handler.** wa
19700 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e  s defined  (usin
19710 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
19720 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f  handler()]) prio
19730 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  r to calling.** 
19740 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68  this routine, th
19750 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61  at other busy ha
19760 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64  ndler is cleared
19770 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  .)^.*/.int sqlit
19780 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
19790 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73  sqlite3*, int ms
197a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
197b0 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20  EF: Convenience 
197c0 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e  Routines For Run
197d0 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a  ning Queries.**.
197e0 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65 67  ** This is a leg
197f0 61 63 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  acy interface th
19800 61 74 20 69 73 20 70 72 65 73 65 72 76 65 64 20  at is preserved 
19810 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
19820 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20  mpatibility..** 
19830 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65  Use of this inte
19840 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63  rface is not rec
19850 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  ommended..**.** 
19860 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62  Definition: A <b
19870 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62  >result table</b
19880 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61  > is memory data
19890 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74   structure creat
198a0 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71  ed by the.** [sq
198b0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
198c0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41  )] interface.  A
198d0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65   result table re
198e0 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d  cords the.** com
198f0 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75  plete query resu
19900 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20  lts from one or 
19910 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a  more queries..**
19920 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f  .** The table co
19930 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61  nceptually has a
19940 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
19950 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75  and columns.  Bu
19960 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65  t.** these numbe
19970 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20  rs are not part 
19980 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
19990 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65  ble itself.  The
199a0 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72  se.** numbers ar
199b0 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72  e obtained separ
199c0 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65  ately.  Let N be
199d0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
199e0 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20  ows.** and M be 
199f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
19a00 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  lumns..**.** A r
19a10 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61  esult table is a
19a20 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
19a30 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  ers to zero-term
19a40 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
19a50 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61  ings..** There a
19a60 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65  re (N+1)*M eleme
19a70 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79  nts in the array
19a80 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70  .  The first M p
19a90 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a  ointers point.**
19aa0 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
19ab0 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
19ac0 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61    contain the na
19ad0 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  mes of the colum
19ae0 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69  ns..** The remai
19af0 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c  ning entries all
19b00 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20   point to query 
19b10 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76  results.  NULL v
19b20 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20  alues result.** 
19b30 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  in NULL pointers
19b40 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  .  All other val
19b50 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72  ues are in their
19b60 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d   UTF-8 zero-term
19b70 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
19b80 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
19b90 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  as returned by [
19ba0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
19bb0 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20  ext()]..**.** A 
19bc0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67  result table mig
19bd0 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e  ht consist of on
19be0 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79  e or more memory
19bf0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a   allocations..**
19c00 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
19c10 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74  to pass a result
19c20 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20   table directly 
19c30 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
19c40 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ()]..** A result
19c50 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65   table should be
19c60 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69   deallocated usi
19c70 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
19c80 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _table()]..**.**
19c90 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65   ^(As an example
19ca0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
19cb0 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70  able format, sup
19cc0 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73  pose a query res
19cd0 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c  ult.** is as fol
19ce0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
19cf0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
19d00 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20          Name    
19d10 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20      | Age.**    
19d20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d      ------------
19d30 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20  -----------.**  
19d40 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20        Alice     
19d50 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20    | 43.**       
19d60 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32   Bob         | 2
19d70 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64  8.**        Cind
19d80 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20  y       | 21.** 
19d90 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
19da0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20  te>.**.** There 
19db0 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28  are two column (
19dc0 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20  M==2) and three 
19dd0 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68  rows (N==3).  Th
19de0 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  us the.** result
19df0 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74   table has 8 ent
19e00 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74  ries.  Suppose t
19e10 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
19e20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20  is stored.** in 
19e30 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61  an array names a
19e40 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61  zResult.  Then a
19e50 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68  zResult holds th
19e60 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a  is content:.**.*
19e70 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
19e80 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  re>.**        az
19e90 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20  Result&#91;0] = 
19ea0 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20  "Name";.**      
19eb0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31    azResult&#91;1
19ec0 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20  ] = "Age";.**   
19ed0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
19ee0 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a  1;2] = "Alice";.
19ef0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
19f00 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22  lt&#91;3] = "43"
19f10 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
19f20 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42  sult&#91;4] = "B
19f30 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ob";.**        a
19f40 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d  zResult&#91;5] =
19f50 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "28";.**       
19f60 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d   azResult&#91;6]
19f70 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20   = "Cindy";.**  
19f80 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
19f90 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a  91;7] = "21";.**
19fa0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
19fb0 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
19fc0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
19fd0 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65  ble() function e
19fe0 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20  valuates one or 
19ff0 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  more.** semicolo
1a000 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20  n-separated SQL 
1a010 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68  statements in th
1a020 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
1a030 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e  d UTF-8.** strin
1a040 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72  g of its 2nd par
1a050 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72  ameter and retur
1a060 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ns a result tabl
1a070 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e  e to the.** poin
1a080 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73  ter given in its
1a090 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a   3rd parameter..
1a0a0 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20  **.** After the 
1a0b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20  application has 
1a0c0 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68  finished with th
1a0d0 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71  e result from sq
1a0e0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1a0f0 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61  ),.** it must pa
1a100 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  ss the result ta
1a110 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73  ble pointer to s
1a120 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1a130 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a  e() in order to.
1a140 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  ** release the m
1a150 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d  emory that was m
1a160 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73  alloced.  Becaus
1a170 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65  e of the way the
1a180 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
1a190 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77  loc()] happens w
1a1a0 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65  ithin sqlite3_ge
1a1b0 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63  t_table(), the c
1a1c0 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  alling.** functi
1a1d0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20  on must not try 
1a1e0 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  to call [sqlite3
1a1f0 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c  _free()] directl
1a200 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c  y.  Only.** [sql
1a210 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1a220 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65  )] is able to re
1a230 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
1a240 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61   properly and sa
1a250 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fely..**.** The 
1a260 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1a270 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  e() interface is
1a280 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20   implemented as 
1a290 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64  a wrapper around
1a2a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
1a2b0 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74  c()].  The sqlit
1a2c0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72  e3_get_table() r
1a2d0 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20  outine does not 
1a2e0 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  have access.** t
1a2f0 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64  o any internal d
1a300 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f  ata structures o
1a310 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73  f SQLite.  It us
1a320 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c  es only the publ
1a330 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ic.** interface 
1a340 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41  defined here.  A
1a350 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c  s a consequence,
1a360 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63   errors that occ
1a370 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61  ur in the.** wra
1a380 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69  pper layer outsi
1a390 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e  de of the intern
1a3a0 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  al [sqlite3_exec
1a3b0 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74  ()] call are not
1a3c0 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e  .** reflected in
1a3d0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
1a3e0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
1a3f0 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b  rcode()] or.** [
1a400 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1a410 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
1a420 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73  3_get_table(.  s
1a430 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1a440 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20       /* An open 
1a450 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
1a460 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
1a470 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65      /* SQL to be
1a480 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20   evaluated */.  
1a490 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c  char ***pazResul
1a4a0 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73  t,    /* Results
1a4b0 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f   of the query */
1a4c0 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20  .  int *pnRow,  
1a4d0 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
1a4e0 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77  er of result row
1a4f0 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
1a500 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d  /.  int *pnColum
1a510 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d  n,        /* Num
1a520 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f  ber of result co
1a530 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65  lumns written he
1a540 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70  re */.  char **p
1a550 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a  zErrmsg       /*
1a560 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74   Error msg writt
1a570 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f  en here */.);.vo
1a580 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  id sqlite3_free_
1a590 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73  table(char **res
1a5a0 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ult);../*.** CAP
1a5b0 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64  I3REF: Formatted
1a5c0 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67   String Printing
1a5d0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
1a5e0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1a5f0 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20  are work-alikes 
1a600 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29  of the "printf()
1a610 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63  " family of func
1a620 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68  tions.** from th
1a630 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
1a640 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rary..**.** ^The
1a650 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1a660 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
1a670 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  mprintf() routin
1a680 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a  es write their.*
1a690 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d  * results into m
1a6a0 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
1a6b0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
1a6c0 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  loc()]..** The s
1a6d0 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
1a6e0 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75  by these two rou
1a6f0 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a  tines should be.
1a700 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b  ** released by [
1a710 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
1a720 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73    ^Both routines
1a730 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c   return a.** NUL
1a740 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71  L pointer if [sq
1a750 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1a760 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
1a770 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20  ocate enough.** 
1a780 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
1a790 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
1a7a0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ing..**.** ^(The
1a7b0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1a7c0 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  f() routine is s
1a7d0 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69  imilar to "snpri
1a7e0 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74  ntf()" from.** t
1a7f0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
1a800 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75  brary.  The resu
1a810 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  lt is written in
1a820 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72  to the.** buffer
1a830 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65   supplied as the
1a840 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1a850 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20  r whose size is 
1a860 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20  given by.** the 
1a870 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
1a880 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f   Note that the o
1a890 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66  rder of the.** f
1a8a0 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74  irst two paramet
1a8b0 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20  ers is reversed 
1a8c0 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e  from snprintf().
1a8d0 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a  )^  This is an.*
1a8e0 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63  * historical acc
1a8f0 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f  ident that canno
1a900 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f  t be fixed witho
1a910 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62  ut breaking.** b
1a920 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
1a930 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20  bility.  ^(Note 
1a940 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65  also that sqlite
1a950 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
1a960 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1a970 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20  r to its buffer 
1a980 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e  instead of the n
1a990 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72  umber of.** char
1a9a0 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20  acters actually 
1a9b0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
1a9c0 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61   buffer.)^  We a
1a9d0 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65  dmit that.** the
1a9e0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
1a9f0 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f  cters written wo
1aa00 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73  uld be a more us
1aa10 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76  eful return.** v
1aa20 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e  alue but we cann
1aa30 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d  ot change the im
1aa40 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1aa50 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1aa60 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75  ().** now withou
1aa70 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61  t breaking compa
1aa80 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
1aa90 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20  ^As long as the 
1aaa0 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67  buffer size is g
1aab0 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f  reater than zero
1aac0 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  , sqlite3_snprin
1aad0 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65  tf().** guarante
1aae0 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66  es that the buff
1aaf0 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72  er is always zer
1ab00 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
1ab10 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  The first.** par
1ab20 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68  ameter "n" is th
1ab30 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20  e total size of 
1ab40 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c  the buffer, incl
1ab50 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a  uding space for.
1ab60 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  ** the zero term
1ab70 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20  inator.  So the 
1ab80 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74  longest string t
1ab90 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c  hat can be compl
1aba0 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e  etely.** written
1abb0 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61   will be n-1 cha
1abc0 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  racters..**.** ^
1abd0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70  The sqlite3_vsnp
1abe0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
1abf0 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72  is a varargs ver
1ac00 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  sion of sqlite3_
1ac10 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a  snprintf()..**.*
1ac20 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1ac30 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73   all implement s
1ac40 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ome additional f
1ac50 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74  ormatting.** opt
1ac60 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73  ions that are us
1ac70 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75  eful for constru
1ac80 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  cting SQL statem
1ac90 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20  ents..** All of 
1aca0 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66  the usual printf
1acb0 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  () formatting op
1acc0 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e  tions apply.  In
1acd0 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65   addition, there
1ace0 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c  .** is are "%q",
1acf0 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20   "%Q", and "%z" 
1ad00 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  options..**.** ^
1ad10 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77  (The %q option w
1ad20 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20  orks like %s in 
1ad30 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75  that it substitu
1ad40 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e  tes a nul-termin
1ad50 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66  ated.** string f
1ad60 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74  rom the argument
1ad70 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61   list.  But %q a
1ad80 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72  lso doubles ever
1ad90 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  y '\'' character
1ada0 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67  ..** %q is desig
1adb0 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ned for use insi
1adc0 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  de a string lite
1add0 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c  ral.)^  By doubl
1ade0 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a  ing each '\''.**
1adf0 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73   character it es
1ae00 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61  capes that chara
1ae10 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20  cter and allows 
1ae20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65  it to be inserte
1ae30 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74  d into.** the st
1ae40 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  ring..**.** For 
1ae50 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20  example, assume 
1ae60 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61  the string varia
1ae70 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69  ble zText contai
1ae80 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f  ns text as follo
1ae90 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1aea0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1aeb0 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49  char *zText = "I
1aec0 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
1aed0 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
1aee0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1aef0 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73  One can use this
1af00 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20   text in an SQL 
1af10 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c  statement as fol
1af20 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1af30 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1af40 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
1af50 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
1af60 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1af70 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c  e VALUES('%q')",
1af80 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
1af90 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
1afa0 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
1afb0 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
1afc0 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
1afd0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1afe0 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25  ** Because the %
1aff0 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20  q format string 
1b000 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27  is used, the '\'
1b010 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a  ' character in z
1b020 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70  Text.** is escap
1b030 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67  ed and the SQL g
1b040 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66  enerated is as f
1b050 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1b060 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1b070 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
1b080 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
1b090 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79  t''s a happy day
1b0a0 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !').** </pre></b
1b0b0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1b0c0 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74   This is correct
1b0d0 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25  .  Had we used %
1b0e0 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c  s instead of %q,
1b0f0 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53   the generated S
1b100 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65  QL.** would have
1b110 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69   looked like thi
1b120 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1b130 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
1b140 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1b150 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61  1 VALUES('It's a
1b160 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a   happy day!');.*
1b170 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1b180 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
1b190 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20   second example 
1b1a0 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78  is an SQL syntax
1b1b0 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65   error.  As a ge
1b1c0 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73  neral rule you s
1b1d0 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20  hould.** always 
1b1e0 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f  use %q instead o
1b1f0 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74  f %s when insert
1b200 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20  ing text into a 
1b210 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a  string literal..
1b220 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f  **.** ^(The %Q o
1b230 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
1b240 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c   %q except it al
1b250 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71  so adds single q
1b260 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20  uotes around.** 
1b270 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74  the outside of t
1b280 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e  he total string.
1b290 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20    Additionally, 
1b2a0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
1b2b0 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d   in the.** argum
1b2c0 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55  ent list is a NU
1b2d0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73  LL pointer, %Q s
1b2e0 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74  ubstitutes the t
1b2f0 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68  ext "NULL" (with
1b300 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75  out.** single qu
1b310 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f  otes).)^  So, fo
1b320 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63  r example, one c
1b330 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20  ould say:.**.** 
1b340 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1b350 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
1b360 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
1b370 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
1b380 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29  table VALUES(%Q)
1b390 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
1b3a0 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
1b3b0 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
1b3c0 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
1b3d0 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
1b3e0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1b3f0 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62  *.** The code ab
1b400 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20  ove will render 
1b410 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74  a correct SQL st
1b420 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a  atement in the z
1b430 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20  SQL.** variable 
1b440 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78  even if the zTex
1b450 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20  t variable is a 
1b460 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
1b470 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66  .** ^(The "%z" f
1b480 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1b490 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22   works like "%s"
1b4a0 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a   but with the.**
1b4b0 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61   addition that a
1b4c0 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20  fter the string 
1b4d0 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e  has been read an
1b4e0 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a  d copied into.**
1b4f0 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71   the result, [sq
1b500 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73  lite3_free()] is
1b510 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69   called on the i
1b520 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a  nput string.)^.*
1b530 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  /.char *sqlite3_
1b540 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
1b550 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a  ar*,...);.char *
1b560 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
1b570 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  (const char*, va
1b580 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71  _list);.char *sq
1b590 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69  lite3_snprintf(i
1b5a0 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
1b5b0 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72  har*, ...);.char
1b5c0 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69   *sqlite3_vsnpri
1b5d0 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
1b5e0 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
1b5f0 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  st);../*.** CAPI
1b600 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
1b610 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65  ocation Subsyste
1b620 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69  m.**.** The SQLi
1b630 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65  te core uses the
1b640 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65  se three routine
1b650 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  s for all of its
1b660 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c   own.** internal
1b670 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1b680 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22  on needs. "Core"
1b690 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
1b6a0 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65   sentence.** doe
1b6b0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70  s not include op
1b6c0 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
1b6d0 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c  pecific VFS impl
1b6e0 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65  ementation.  The
1b6f0 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20  .** Windows VFS 
1b700 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c  uses native mall
1b710 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
1b720 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69  for some operati
1b730 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ons..**.** ^The 
1b740 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1b750 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1b760 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1b770 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  block.** of memo
1b780 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  ry at least N by
1b790 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77  tes in length, w
1b7a0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61  here N is the pa
1b7b0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  rameter..** ^If 
1b7c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1b7d0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62   is unable to ob
1b7e0 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20  tain sufficient 
1b7f0 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  free.** memory, 
1b800 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  it returns a NUL
1b810 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20  L pointer.  ^If 
1b820 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  the parameter N 
1b830 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  to.** sqlite3_ma
1b840 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
1b850 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  r negative then 
1b860 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1b870 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55   returns.** a NU
1b880 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1b890 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
1b8a0 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61  e3_free() with a
1b8b0 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75   pointer previou
1b8c0 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  sly returned.** 
1b8d0 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
1b8e0 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
1b8f0 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65  ealloc() release
1b900 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f  s that memory so
1b910 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68  .** that it migh
1b920 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54  t be reused.  ^T
1b930 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  he sqlite3_free(
1b940 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20  ) routine is.** 
1b950 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61  a no-op if is ca
1b960 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
1b970 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69   pointer.  Passi
1b980 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ng a NULL pointe
1b990 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  r.** to sqlite3_
1b9a0 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65  free() is harmle
1b9b0 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67  ss.  After being
1b9c0 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a   freed, memory.*
1b9d0 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72  * should neither
1b9e0 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69   be read nor wri
1b9f0 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64  tten.  Even read
1ba00 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ing previously f
1ba10 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d  reed.** memory m
1ba20 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61  ight result in a
1ba30 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
1ba40 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76  ult or other sev
1ba50 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65  ere error..** Me
1ba60 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c  mory corruption,
1ba70 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
1ba80 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20  fault, or other 
1ba90 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20  severe error.** 
1baa0 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
1bab0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
1bac0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
1bad0 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
1bae0 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74   that.** was not
1baf0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
1bb00 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1bb10 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
1bb20 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  oc()..**.** ^(Th
1bb30 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
1bb40 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  c() interface at
1bb50 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65  tempts to resize
1bb60 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f   a.** prior memo
1bb70 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
1bb80 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62   be at least N b
1bb90 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73  ytes, where N is
1bba0 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   the.** second p
1bbb0 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d  arameter.  The m
1bbc0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1bbd0 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69   to be resized i
1bbe0 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70  s the first.** p
1bbf0 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66  arameter.)^ ^ If
1bc00 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
1bc10 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1bc20 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
1bc30 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
1bc40 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72  hen its behavior
1bc50 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
1bc60 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
1bc70 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68  te3_malloc(N) wh
1bc80 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
1bc90 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
1bca0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1bcb0 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  ()..** ^If the s
1bcc0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1bcd0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1bce0 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  oc() is zero or.
1bcf0 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
1bd00 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
1bd10 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
1bd20 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
1bd30 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20  sqlite3_free(P) 
1bd40 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66  where P is the f
1bd50 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
1bd60 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1bd70 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33  c()..** ^sqlite3
1bd80 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
1bd90 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1bda0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
1bdb0 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  ion.** of at lea
1bdc0 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
1bdd0 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75  ze or NULL if su
1bde0 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
1bdf0 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a  is unavailable..
1be00 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20  ** ^If M is the 
1be10 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f  size of the prio
1be20 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  r allocation, th
1be30 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65  en min(N,M) byte
1be40 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f  s.** of the prio
1be50 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65  r allocation are
1be60 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65   copied into the
1be70 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75   beginning of bu
1be80 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ffer returned.**
1be90 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   by sqlite3_real
1bea0 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72  loc() and the pr
1beb0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
1bec0 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  s freed..** ^If 
1bed0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1bee0 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20  ) returns NULL, 
1bef0 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61  then the prior a
1bf00 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  llocation.** is 
1bf10 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a  not freed..**.**
1bf20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74   ^The memory ret
1bf30 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1bf40 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71  _malloc() and sq
1bf50 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a  lite3_realloc().
1bf60 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69  ** is always ali
1bf70 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74  gned to at least
1bf80 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64   an 8 byte bound
1bf90 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20  ary, or to a.** 
1bfa0 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  4 byte boundary 
1bfb0 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34  if the [SQLITE_4
1bfc0 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41  _BYTE_ALIGNED_MA
1bfd0 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  LLOC] compile-ti
1bfe0 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20  me.** option is 
1bff0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53  used..**.** In S
1c000 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
1c010 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69  5.0 and 3.5.1, i
1c020 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74  t was possible t
1c030 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  o define.** the 
1c040 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f  SQLITE_OMIT_MEMO
1c050 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68  RY_ALLOCATION wh
1c060 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20  ich would cause 
1c070 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20  the built-in.** 
1c080 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1c090 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1c0a0 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20   to be omitted. 
1c0b0 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79   That capability
1c0c0 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  .** is no longer
1c0d0 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79   provided.  Only
1c0e0 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
1c0f0 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20   allocators can 
1c100 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50  be used..**.** P
1c110 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76  rior to SQLite v
1c120 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74  ersion 3.7.10, t
1c130 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e  he Windows OS in
1c140 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61  terface layer ca
1c150 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74  lled.** the syst
1c160 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  em malloc() and 
1c170 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20  free() directly 
1c180 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a  when converting.
1c190 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74  ** filenames bet
1c1a0 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65  ween the UTF-8 e
1c1b0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20  ncoding used by 
1c1c0 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68  SQLite.** and wh
1c1d0 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20  atever filename 
1c1e0 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
1c1f0 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c   by the particul
1c200 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e  ar Windows.** in
1c210 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d  stallation.  Mem
1c220 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
1c230 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63  rrors were detec
1c240 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79  ted, but.** they
1c250 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62   were reported b
1c260 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43  ack as [SQLITE_C
1c270 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b  ANTOPEN] or.** [
1c280 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61  SQLITE_IOERR] ra
1c290 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
1c2a0 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
1c2b0 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  The pointer argu
1c2c0 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65  ments to [sqlite
1c2d0 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73  3_free()] and [s
1c2e0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1c2f0 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74  ].** must be eit
1c300 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65  her NULL or else
1c310 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e   pointers obtain
1c320 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a  ed from a prior.
1c330 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ** invocation of
1c340 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1c350 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1c360 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
1c370 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20  have.** not yet 
1c380 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a  been released..*
1c390 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
1c3a0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65  tion must not re
1c3b0 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20  ad or write any 
1c3c0 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f  part of.** a blo
1c3d0 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74  ck of memory aft
1c3e0 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72  er it has been r
1c3f0 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a  eleased using.**
1c400 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1c410 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
1c420 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69  alloc()]..*/.voi
1c430 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  d *sqlite3_mallo
1c440 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71  c(int);.void *sq
1c450 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f  lite3_realloc(vo
1c460 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  id*, int);.void 
1c470 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69  sqlite3_free(voi
1c480 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1c490 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
1c4a0 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63  ocator Statistic
1c4b0 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70  s.**.** SQLite p
1c4c0 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77  rovides these tw
1c4d0 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72  o interfaces for
1c4e0 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68   reporting on th
1c4f0 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74  e status.** of t
1c500 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  he [sqlite3_mall
1c510 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  oc()], [sqlite3_
1c520 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  free()], and [sq
1c530 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1c540 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68  .** routines, wh
1c550 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69  ich form the bui
1c560 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
1c570 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
1c580 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  m..**.** ^The [s
1c590 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1c5a0 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  ed()] routine re
1c5b0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
1c5c0 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20   of bytes.** of 
1c5d0 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79  memory currently
1c5e0 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61   outstanding (ma
1c5f0 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66  lloced but not f
1c600 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b  reed)..** ^The [
1c610 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1c620 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74  ighwater()] rout
1c630 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
1c640 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65  maximum.** value
1c650 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   of [sqlite3_mem
1c660 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63  ory_used()] sinc
1c670 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  e the high-water
1c680 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73   mark.** was las
1c690 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76  t reset.  ^The v
1c6a0 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
1c6b0 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
1c6c0 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  y_used()] and.**
1c6d0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1c6e0 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e  _highwater()] in
1c6f0 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65  clude any overhe
1c700 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53  ad.** added by S
1c710 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70  QLite in its imp
1c720 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
1c730 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1c740 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76  ],.** but not ov
1c750 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20  erhead added by 
1c760 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69  the any underlyi
1c770 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72  ng system librar
1c780 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68  y.** routines th
1c790 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  at [sqlite3_mall
1c7a0 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a  oc()] may call..
1c7b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72  **.** ^The memor
1c7c0 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  y high-water mar
1c7d0 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68  k is reset to th
1c7e0 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
1c7f0 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  of.** [sqlite3_m
1c800 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66  emory_used()] if
1c810 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
1c820 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
1c830 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1c840 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73  _highwater()] is
1c850 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c   true.  ^The val
1c860 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ue returned.** b
1c870 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
1c880 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20  y_highwater(1)] 
1c890 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  is the high-wate
1c8a0 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20  r mark.** prior 
1c8b0 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f  to the reset..*/
1c8c0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
1c8d0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1c8e0 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65  ed(void);.sqlite
1c8f0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
1c900 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1c910 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b  (int resetFlag);
1c920 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c930 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20  : Pseudo-Random 
1c940 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72  Number Generator
1c950 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f  .**.** SQLite co
1c960 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75  ntains a high-qu
1c970 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e  ality pseudo-ran
1c980 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72  dom number gener
1c990 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64  ator (PRNG) used
1c9a0 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61   to.** select ra
1c9b0 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f  ndom [ROWID | RO
1c9c0 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72  WIDs] when inser
1c9d0 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73  ting new records
1c9e0 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68   into a table th
1c9f0 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73  at.** already us
1ca00 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70  es the largest p
1ca10 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e  ossible [ROWID].
1ca20 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c    The PRNG is al
1ca30 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  so used for.** t
1ca40 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64  he build-in rand
1ca50 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62  om() and randomb
1ca60 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69  lob() SQL functi
1ca70 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72  ons.  This inter
1ca80 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61  face allows.** a
1ca90 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61  pplications to a
1caa0 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50  ccess the same P
1cab0 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75  RNG for other pu
1cac0 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  rposes..**.** ^A
1cad0 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f   call to this ro
1cae0 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62  utine stores N b
1caf0 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
1cb00 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50  ss into buffer P
1cb10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
1cb20 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75  st time this rou
1cb30 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  tine is invoked 
1cb40 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c  (either internal
1cb50 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20  ly or by.** the 
1cb60 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65  application) the
1cb70 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20   PRNG is seeded 
1cb80 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
1cb90 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
1cba0 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
1cbb0 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
1cbc0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
1cbd0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
1cbe0 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75   ^On all subsequ
1cbf0 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c  ent invocations,
1cc00 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64   the pseudo-rand
1cc10 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61  omness is genera
1cc20 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c  ted.** internall
1cc30 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65  y and without re
1cc40 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73  course to the [s
1cc50 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e  qlite3_vfs] xRan
1cc60 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f  domness.** metho
1cc70 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  d..*/.void sqlit
1cc80 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e  e3_randomness(in
1cc90 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a  t N, void *P);..
1cca0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1ccb0 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
1ccc0 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
1ccd0 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  acks.**.** ^This
1cce0 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65   routine registe
1ccf0 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  rs an authorizer
1cd00 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61   callback with a
1cd10 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
1cd20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1cd30 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69  ion], supplied i
1cd40 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
1cd50 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75  ment..** ^The au
1cd60 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1cd70 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20  k is invoked as 
1cd80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
1cd90 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65  re being compile
1cda0 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
1cdb0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
1cdc0 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c  ts variants [sql
1cdd0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1cde0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
1cdf0 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64  prepare16()] and
1ce00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1ce10 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20  e16_v2()].  ^At 
1ce20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74  various.** point
1ce30 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d  s during the com
1ce40 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73  pilation process
1ce50 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65  , as logic is be
1ce60 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74  ing created.** t
1ce70 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
1ce80 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61  s actions, the a
1ce90 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1cea0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  ck is invoked to
1ceb0 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65  .** see if those
1cec0 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c   actions are all
1ced0 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68  owed.  ^The auth
1cee0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1cef0 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
1cf00 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20   [SQLITE_OK] to 
1cf10 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e  allow the action
1cf20 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  , [SQLITE_IGNORE
1cf30 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68  ] to disallow th
1cf40 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63  e.** specific ac
1cf50 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74  tion but allow t
1cf60 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1cf70 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20   to continue to 
1cf80 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20  be.** compiled, 
1cf90 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
1cfa0 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e   to cause the en
1cfb0 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65  tire SQL stateme
1cfc0 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65  nt to be.** reje
1cfd0 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72  cted with an err
1cfe0 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74  or.  ^If the aut
1cff0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1d000 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
1d010 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
1d020 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1d030 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f  , [SQLITE_OK], o
1d040 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a  r [SQLITE_DENY].
1d050 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c  ** then the [sql
1d060 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1d070 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
1d080 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
1d090 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68  ered.** the auth
1d0a0 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
1d0b0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
1d0c0 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  essage..**.** Wh
1d0d0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
1d0e0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1d0f0 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  OK], that means 
1d100 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
1d110 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b   requested is ok
1d120 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c  .  ^When the cal
1d130 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
1d140 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65  QLITE_DENY], the
1d150 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1d160 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
1d170 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
1d180 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
1d190 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77  .** authorizer w
1d1a0 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
1d1b0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65   error message e
1d1c0 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a  xplaining that.*
1d1d0 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69  * access is deni
1d1e0 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ed. .**.** ^The 
1d1f0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1d200 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
1d210 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  r callback is a 
1d220 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72  copy of the thir
1d230 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
1d240 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  o the sqlite3_se
1d250 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69  t_authorizer() i
1d260 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73  nterface. ^The s
1d270 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  econd parameter.
1d280 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
1d290 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
1d2a0 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
1d2b0 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61  action code] tha
1d2c0 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
1d2d0 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
1d2e0 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
1d2f0 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72  rized. ^The thir
1d300 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20  d through sixth 
1d310 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
1d320 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72   the callback ar
1d330 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
1d340 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63  d strings that c
1d350 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61  ontain additiona
1d360 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f  l.** details abo
1d370 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f  ut the action to
1d380 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a   be authorized..
1d390 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  **.** ^If the ac
1d3a0 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
1d3b0 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e  LITE_READ].** an
1d3c0 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
1d3d0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49  eturns [SQLITE_I
1d3e0 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a  GNORE] then the.
1d3f0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
1d400 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e  tement] statemen
1d410 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64  t is constructed
1d420 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a   to substitute.*
1d430 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69  * a NULL value i
1d440 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74  n place of the t
1d450 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
1d460 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62   would have.** b
1d470 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c  een read if [SQL
1d480 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e  ITE_OK] had been
1d490 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
1d4a0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a  [SQLITE_IGNORE].
1d4b0 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65  ** return can be
1d4c0 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e   used to deny an
1d4d0 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20   untrusted user 
1d4e0 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69  access to indivi
1d4f0 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20  dual.** columns 
1d500 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e  of a table..** ^
1d510 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
1d520 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45  de is [SQLITE_DE
1d530 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61  LETE] and the ca
1d540 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
1d550 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  * [SQLITE_IGNORE
1d560 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45  ] then the [DELE
1d570 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72  TE] operation pr
1d580 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a  oceeds but the.*
1d590 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69  * [truncate opti
1d5a0 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73  mization] is dis
1d5b0 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f  abled and all ro
1d5c0 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69  ws are deleted i
1d5d0 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a  ndividually..**.
1d5e0 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  ** An authorizer
1d5f0 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73   is used when [s
1d600 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
1d610 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53   preparing].** S
1d620 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72  QL statements fr
1d630 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  om an untrusted 
1d640 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72  source, to ensur
1d650 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73  e that the SQL s
1d660 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20  tatements.** do 
1d670 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73  not try to acces
1d680 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20  s data they are 
1d690 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73  not allowed to s
1d6a0 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79  ee, or that they
1d6b0 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74   do not.** try t
1d6c0 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69  o execute malici
1d6d0 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74  ous statements t
1d6e0 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64  hat damage the d
1d6f0 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a  atabase.  For.**
1d700 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
1d710 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c  lication may all
1d720 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74  ow a user to ent
1d730 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  er arbitrary.** 
1d740 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20  SQL queries for 
1d750 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20  evaluation by a 
1d760 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74  database.  But t
1d770 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
1d780 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20  oes.** not want 
1d790 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61  the user to be a
1d7a0 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69  ble to make arbi
1d7b0 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f  trary changes to
1d7c0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
1d7d0 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  .  An authorizer
1d7e0 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70   could then be p
1d7f0 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c  ut in place whil
1d800 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e  e the.** user-en
1d810 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69  tered SQL is bei
1d820 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
1d830 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20  are | prepared] 
1d840 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77  that.** disallow
1d850 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63  s everything exc
1d860 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  ept [SELECT] sta
1d870 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41  tements..**.** A
1d880 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
1d890 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73   need to process
1d8a0 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73   SQL from untrus
1d8b0 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d  ted sources.** m
1d8c0 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64  ight also consid
1d8d0 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f  er lowering reso
1d8e0 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e  urce limits usin
1d8f0 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
1d900 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74  ()].** and limit
1d910 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a  ing database siz
1d920 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78  e using the [max
1d930 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
1d940 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69  AGMA].** in addi
1d950 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e  tion to using an
1d960 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a   authorizer..**.
1d970 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67  ** ^(Only a sing
1d980 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  le authorizer ca
1d990 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e  n be in place on
1d9a0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
1d9b0 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74  ection.** at a t
1d9c0 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20  ime.  Each call 
1d9d0 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
1d9e0 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69  uthorizer overri
1d9f0 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69  des the.** previ
1da00 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69  ous call.)^  ^Di
1da10 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72  sable the author
1da20 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69  izer by installi
1da30 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61  ng a NULL callba
1da40 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  ck..** The autho
1da50 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65  rizer is disable
1da60 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
1da70 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
1da80 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
1da90 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
1daa0 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
1dab0 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
1dac0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
1dad0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75  t invoked the au
1dae0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1daf0 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  k..** Note that 
1db00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1db10 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
1db20 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
1db30 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
1db40 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1db50 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
1db60 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
1db70 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
1db80 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  aph..**.** ^When
1db90 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1dba0 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20  e_v2()] is used 
1dbb0 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61  to prepare a sta
1dbc0 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73  tement, the.** s
1dbd0 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62  tatement might b
1dbe0 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75  e re-prepared du
1dbf0 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ring [sqlite3_st
1dc00 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a  ep()] due to a .
1dc10 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  ** schema change
1dc20 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70  .  Hence, the ap
1dc30 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
1dc40 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
1dc50 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68  .** correct auth
1dc60 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1dc70 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65  remains in place
1dc80 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c   during the [sql
1dc90 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
1dca0 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  .** ^Note that t
1dcb0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1dcc0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1dcd0 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a  d only during.**
1dce0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1dcf0 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
1dd00 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61  ants.  Authoriza
1dd10 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70  tion is not.** p
1dd20 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20  erformed during 
1dd30 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61  statement evalua
1dd40 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33  tion in [sqlite3
1dd50 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73  _step()], unless
1dd60 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e  .** as stated in
1dd70 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61   the previous pa
1dd80 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33  ragraph, sqlite3
1dd90 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a  _step() invokes.
1dda0 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ** sqlite3_prepa
1ddb0 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65  re_v2() to repre
1ddc0 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
1ddd0 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20   after a schema 
1dde0 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73  change..*/.int s
1ddf0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1de00 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33  rizer(.  sqlite3
1de10 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68  *,.  int (*xAuth
1de20 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
1de30 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
1de40 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1de50 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20  const char*),.  
1de60 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a  void *pUserData.
1de70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1de80 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52  EF: Authorizer R
1de90 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  eturn Codes.**.*
1dea0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
1deb0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
1dec0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1ded0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75  ack function] mu
1dee0 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74  st.** return eit
1def0 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  her [SQLITE_OK] 
1df00 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  or one of these 
1df10 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e  two constants in
1df20 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67   order.** to sig
1df30 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68  nal SQLite wheth
1df40 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63  er or not the ac
1df50 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
1df60 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b  d.  See the.** [
1df70 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1df80 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
1df90 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  zer documentatio
1dfa0 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  n] for additiona
1dfb0 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
1dfc0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
1dfd0 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  t SQLITE_IGNORE 
1dfe0 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20  is also used as 
1dff0 61 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41  a [SQLITE_ROLLBA
1e000 43 4b 20 7c 20 72 65 74 75 72 6e 20 63 6f 64 65  CK | return code
1e010 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 5b 73  ].** from the [s
1e020 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63  qlite3_vtab_on_c
1e030 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72  onflict()] inter
1e040 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  face..*/.#define
1e050 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31   SQLITE_DENY   1
1e060 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20     /* Abort the 
1e070 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69  SQL statement wi
1e080 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23  th an error */.#
1e090 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47  define SQLITE_IG
1e0a0 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27  NORE 2   /* Don'
1e0b0 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20  t allow access, 
1e0c0 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61  but don't genera
1e0d0 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a  te an error */..
1e0e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1e0f0 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f  Authorizer Actio
1e100 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  n Codes.**.** Th
1e110 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
1e120 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74  uthorizer()] int
1e130 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
1e140 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
1e150 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20  tion.** that is 
1e160 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f  invoked to autho
1e170 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c  rize certain SQL
1e180 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f   statement actio
1e190 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ns.  The.** seco
1e1a0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
1e1b0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
1e1c0 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20  an integer code 
1e1d0 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
1e1e0 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73  * what action is
1e1f0 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65   being authorize
1e200 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68  d.  These are th
1e210 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e  e integer action
1e220 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74   codes that.** t
1e230 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1e240 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61  llback may be pa
1e250 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ssed..**.** Thes
1e260 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61  e action code va
1e270 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61  lues signify wha
1e280 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74  t kind of operat
1e290 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20  ion is to be.** 
1e2a0 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
1e2b0 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72   3rd and 4th par
1e2c0 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61  ameters to the a
1e2d0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20  uthorization.** 
1e2e0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1e2f0 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65  n will be parame
1e300 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70  ters or NULL dep
1e310 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20  ending on which 
1e320 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65  of these.** code
1e330 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  s is used as the
1e340 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1e350 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70 61  r.  ^(The 5th pa
1e360 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a  rameter to the.*
1e370 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  * authorizer cal
1e380 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d  lback is the nam
1e390 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
1e3a0 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70  e ("main", "temp
1e3b0 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61  ",.** etc.) if a
1e3c0 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54  pplicable.)^  ^T
1e3d0 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72  he 6th parameter
1e3e0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
1e3f0 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  er callback.** i
1e400 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1e410 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69  e inner-most tri
1e420 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61  gger or view tha
1e430 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  t is responsible
1e440 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65   for.** the acce
1e450 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55  ss attempt or NU
1e460 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73  LL if this acces
1e470 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72  s attempt is dir
1e480 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f  ectly from.** to
1e490 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65  p-level SQL code
1e4a0 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ..*/./**********
1e4b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e4c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e4d0 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 3rd **********
1e4e0 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 4th *********
1e4f0 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  **/.#define SQLI
1e500 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20  TE_CREATE_INDEX 
1e510 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20           1   /* 
1e520 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1e530 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1e540 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e550 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20  E_CREATE_TABLE  
1e560 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54          2   /* T
1e570 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1e580 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1e590 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e5a0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44  _CREATE_TEMP_IND
1e5b0 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e  EX     3   /* In
1e5c0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1e5d0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1e5e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e5f0 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c  CREATE_TEMP_TABL
1e600 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62  E     4   /* Tab
1e610 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1e620 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1e630 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1e640 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47  REATE_TEMP_TRIGG
1e650 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67  ER   5   /* Trig
1e660 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
1e670 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1e680 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1e690 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20  EATE_TEMP_VIEW  
1e6a0 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20      6   /* View 
1e6b0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
1e6c0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1e6d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1e6e0 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20  ATE_TRIGGER     
1e6f0 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65     7   /* Trigge
1e700 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1e710 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1e720 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1e730 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  TE_VIEW         
1e740 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    8   /* View Na
1e750 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1e760 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1e770 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54  ine SQLITE_DELET
1e780 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
1e790 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   9   /* Table Na
1e7a0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1e7b0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1e7c0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49  ne SQLITE_DROP_I
1e7d0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31  NDEX           1
1e7e0 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  0   /* Index Nam
1e7f0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1e800 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1e810 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41  e SQLITE_DROP_TA
1e820 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31  BLE           11
1e830 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1e840 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1e850 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1e860 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
1e870 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20  P_INDEX      12 
1e880 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1e890 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1e8a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1e8b0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
1e8c0 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20  _TABLE      13  
1e8d0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1e8e0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1e8f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1e900 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
1e910 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20  TRIGGER    14   
1e920 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1e930 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1e940 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1e950 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56  LITE_DROP_TEMP_V
1e960 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f  IEW       15   /
1e970 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1e980 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1e990 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1e9a0 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52  ITE_DROP_TRIGGER
1e9b0 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a           16   /*
1e9c0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1e9d0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1e9e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e9f0 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20  TE_DROP_VIEW    
1ea00 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20          17   /* 
1ea10 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1ea20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1ea30 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ea40 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20  E_INSERT        
1ea50 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54         18   /* T
1ea60 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1ea70 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1ea80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ea90 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
1eaa0 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72        19   /* Pr
1eab0 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73  agma Name     1s
1eac0 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f  t arg or NULL */
1ead0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1eae0 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
1eaf0 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62       20   /* Tab
1eb00 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
1eb10 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
1eb20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1eb30 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
1eb40 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c      21   /* NULL
1eb50 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c              NULL
1eb60 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1eb70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
1eb80 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20  ANSACTION       
1eb90 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61     22   /* Opera
1eba0 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20  tion       NULL 
1ebb0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1ebc0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44  efine SQLITE_UPD
1ebd0 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
1ebe0 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    23   /* Table 
1ebf0 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
1ec00 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1ec10 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41  fine SQLITE_ATTA
1ec20 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
1ec30 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d   24   /* Filenam
1ec40 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  e        NULL   
1ec50 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1ec60 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43  ine SQLITE_DETAC
1ec70 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
1ec80 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  25   /* Database
1ec90 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20   Name   NULL    
1eca0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1ecb0 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f  ne SQLITE_ALTER_
1ecc0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
1ecd0 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  6   /* Database 
1ece0 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d  Name   Table Nam
1ecf0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1ed00 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58  e SQLITE_REINDEX
1ed10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37                27
1ed20 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1ed30 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1ed40 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1ed50 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20   SQLITE_ANALYZE 
1ed60 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20               28 
1ed70 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1ed80 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1ed90 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1eda0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54  SQLITE_CREATE_VT
1edb0 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20  ABLE        29  
1edc0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1edd0 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
1ede0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1edf0 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c  QLITE_DROP_VTABL
1ee00 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20  E          30   
1ee10 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1ee20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
1ee30 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1ee40 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20  LITE_FUNCTION   
1ee50 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f            31   /
1ee60 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
1ee70 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20    Function Name 
1ee80 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1ee90 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20  ITE_SAVEPOINT   
1eea0 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a           32   /*
1eeb0 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
1eec0 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20   Savepoint Name 
1eed0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1eee0 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20  TE_COPY         
1eef0 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20           0   /* 
1ef00 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a  No longer used *
1ef10 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
1ef20 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50  F: Tracing And P
1ef30 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f  rofiling Functio
1ef40 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ns.**.** These r
1ef50 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72  outines register
1ef60 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1ef70 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ons that can be 
1ef80 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63  used for.** trac
1ef90 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e  ing and profilin
1efa0 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
1efb0 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
1efc0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  s..**.** ^The ca
1efd0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1efe0 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
1eff0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73  lite3_trace() is
1f000 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76   invoked at.** v
1f010 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65  arious times whe
1f020 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
1f030 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20  nt is being run 
1f040 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  by [sqlite3_step
1f050 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ()]..** ^The sql
1f060 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
1f070 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1f080 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65   with a UTF-8 re
1f090 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a  ndering of the.*
1f0a0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
1f0b0 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74  text as the stat
1f0c0 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69  ement first begi
1f0d0 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a  ns executing..**
1f0e0 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71   ^(Additional sq
1f0f0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
1f100 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63  llbacks might oc
1f110 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74  cur.** as each t
1f120 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67  riggered subprog
1f130 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20  ram is entered. 
1f140 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66   The callbacks f
1f150 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63  or triggers.** c
1f160 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53  ontain a UTF-8 S
1f170 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20  QL comment that 
1f180 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74  identifies the t
1f190 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20  rigger.)^.**.** 
1f1a0 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43  The [SQLITE_TRAC
1f1b0 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f  E_SIZE_LIMIT] co
1f1c0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
1f1d0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
1f1e0 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65   limit.** the le
1f1f0 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70  ngth of [bound p
1f200 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73  arameter] expans
1f210 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75  ion in the outpu
1f220 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61  t of sqlite3_tra
1f230 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ce()..**.** ^The
1f240 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1f250 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
1f260 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
1f270 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
1f280 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
1f290 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
1f2a0 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
1f2b0 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73  allback contains
1f2c0 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
1f2d0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
1f2e0 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20  and an estimate 
1f2f0 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
1f300 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e  me.** of how lon
1f310 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  g that statement
1f320 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e   took to run.  ^
1f330 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
1f340 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20  back.** time is 
1f350 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f  in units of nano
1f360 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72  seconds, however
1f370 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   the current imp
1f380 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69  lementation.** i
1f390 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f  s only capable o
1f3a0 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65  f millisecond re
1f3b0 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20  solution so the 
1f3c0 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66  six least signif
1f3d0 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20  icant.** digits 
1f3e0 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20  in the time are 
1f3f0 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75  meaningless.  Fu
1f400 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
1f410 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74   SQLite.** might
1f420 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72   provide greater
1f430 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74   resolution on t
1f440 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c  he profiler call
1f450 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71  back.  The.** sq
1f460 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
1f470 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73  function is cons
1f480 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e  idered experimen
1f490 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75  tal and is.** su
1f4a0 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
1f4b0 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
1f4c0 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ns of SQLite..*/
1f4d0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74  .void *sqlite3_t
1f4e0 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76  race(sqlite3*, v
1f4f0 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69  oid(*xTrace)(voi
1f500 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  d*,const char*),
1f510 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f   void*);.SQLITE_
1f520 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69  EXPERIMENTAL voi
1f530 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  d *sqlite3_profi
1f540 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20  le(sqlite3*,.   
1f550 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28  void(*xProfile)(
1f560 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
1f570 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  *,sqlite3_uint64
1f580 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
1f590 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72  * CAPI3REF: Quer
1f5a0 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62  y Progress Callb
1f5b0 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  acks.**.** ^The 
1f5c0 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
1f5d0 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50  _handler(D,N,X,P
1f5e0 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
1f5f0 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  es the callback.
1f600 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f  ** function X to
1f610 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69   be invoked peri
1f620 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20  odically during 
1f630 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c  long running cal
1f640 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
1f650 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69  3_exec()], [sqli
1f660 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20  te3_step()] and 
1f670 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
1f680 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74  le()] for.** dat
1f690 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1f6a0 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20   D.  An example 
1f6b0 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20  use for this.** 
1f6c0 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20  interface is to 
1f6d0 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74  keep a GUI updat
1f6e0 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67  ed during a larg
1f6f0 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  e query..**.** ^
1f700 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20  The parameter P 
1f710 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
1f720 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  h as the only pa
1f730 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a  rameter to the .
1f740 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
1f750 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61  tion X.  ^The pa
1f760 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65  rameter N is the
1f770 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d   approximate num
1f780 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74  ber of .** [virt
1f790 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74  ual machine inst
1f7a0 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61  ructions] that a
1f7b0 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74  re evaluated bet
1f7c0 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a  ween successive.
1f7d0 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
1f7e0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58  f the callback X
1f7f0 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73  .  ^If N is less
1f800 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74   than one then t
1f810 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68  he progress.** h
1f820 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c  andler is disabl
1f830 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20  ed..**.** ^Only 
1f840 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73  a single progres
1f850 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65  s handler may be
1f860 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20   defined at one 
1f870 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74  time per.** [dat
1f880 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1f890 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77  ]; setting a new
1f8a0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1f8b0 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a  r cancels the.**
1f8c0 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74   old one.  ^Sett
1f8d0 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20  ing parameter X 
1f8e0 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73  to NULL disables
1f8f0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
1f900 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70  ndler..** ^The p
1f910 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
1f920 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64  is also disabled
1f930 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f   by setting N to
1f940 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a   a value less.**
1f950 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e   than 1..**.** ^
1f960 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  If the progress 
1f970 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1f980 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f   non-zero, the o
1f990 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69  peration is.** i
1f9a0 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69  nterrupted.  Thi
1f9b0 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65  s feature can be
1f9c0 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
1f9d0 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22  nt a.** "Cancel"
1f9e0 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49   button on a GUI
1f9f0 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67   progress dialog
1fa00 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20   box..**.** The 
1fa10 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1fa20 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
1fa30 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
1fa40 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
1fa50 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
1fa60 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
1fa70 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67  invoked the prog
1fa80 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
1fa90 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
1faa0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1fab0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
1fac0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
1fad0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
1fae0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
1faf0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
1fb00 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
1fb10 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
1fb20 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  **.*/.void sqlit
1fb30 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
1fb40 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
1fb50 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  t, int(*)(void*)
1fb60 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
1fb70 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69   CAPI3REF: Openi
1fb80 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73  ng A New Databas
1fb90 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a  e Connection.**.
1fba0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
1fbb0 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74  es open an SQLit
1fbc0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
1fbd0 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20  as specified by 
1fbe0 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  the .** filename
1fbf0 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20   argument. ^The 
1fc00 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
1fc10 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
1fc20 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a   as UTF-8 for.**
1fc30 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1fc40 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
1fc50 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46  _v2() and as UTF
1fc60 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
1fc70 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20  e byte.** order 
1fc80 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
1fc90 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62  16(). ^(A [datab
1fca0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1fcb0 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c  handle is usuall
1fcc0 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e  y.** returned in
1fcd0 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20   *ppDb, even if 
1fce0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  an error occurs.
1fcf0 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70    The only excep
1fd00 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20  tion is that.** 
1fd10 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  if SQLite is una
1fd20 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
1fd30 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
1fd40 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
1fd50 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77  ect,.** a NULL w
1fd60 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69  ill be written i
1fd70 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61  nto *ppDb instea
1fd80 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74  d of a pointer t
1fd90 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a  o the [sqlite3].
1fda0 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49  ** object.)^ ^(I
1fdb0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  f the database i
1fdc0 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72  s opened (and/or
1fdd0 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73   created) succes
1fde0 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20  sfully, then.** 
1fdf0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
1fe00 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
1fe10 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
1fe20 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
1fe30 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  )^ ^The.** [sqli
1fe40 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72  te3_errmsg()] or
1fe50 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1fe60 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63  16()] routines c
1fe70 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
1fe80 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69  tain.** an Engli
1fe90 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63  sh language desc
1fea0 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65  ription of the e
1feb0 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  rror following a
1fec0 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a   failure of any.
1fed0 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
1fee0 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65  3_open() routine
1fef0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  s..**.** ^The de
1ff00 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66  fault encoding f
1ff10 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
1ff20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66  will be UTF-8 if
1ff30 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
1ff40 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
1ff50 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  en_v2() is calle
1ff60 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20  d and.** UTF-16 
1ff70 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
1ff80 74 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69  te order if sqli
1ff90 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20  te3_open16() is 
1ffa0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74  used..**.** Whet
1ffb0 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72  her or not an er
1ffc0 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20  ror occurs when 
1ffd0 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65  it is opened, re
1ffe0 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63  sources.** assoc
1fff0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
20000 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
20010 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75  ion] handle shou
20020 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62  ld be released b
20030 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20  y.** passing it 
20040 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  to [sqlite3_clos
20050 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20  e()] when it is 
20060 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72  no longer requir
20070 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
20080 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
20090 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20  interface works 
200a0 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65  like sqlite3_ope
200b0 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  n().** except th
200c0 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77  at it accepts tw
200d0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72  o additional par
200e0 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69  ameters for addi
200f0 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a  tional control.*
20100 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64  * over the new d
20110 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20120 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73  on.  ^(The flags
20130 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
20140 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
20150 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20  () can take one 
20160 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77  of.** the follow
20170 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73  ing three values
20180 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  , optionally com
20190 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a  bined with the .
201a0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
201b0 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  NOMUTEX], [SQLIT
201c0 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
201d0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
201e0 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a  SHAREDCACHE],.**
201f0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
20200 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64  IVATECACHE], and
20210 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  /or [SQLITE_OPEN
20220 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a  _URI] flags:)^.*
20230 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c  *.** <dl>.** ^(<
20240 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
20250 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a  READONLY]</dt>.*
20260 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
20270 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20  se is opened in 
20280 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20  read-only mode. 
20290 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
202a0 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72   does not.** alr
202b0 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65  eady exist, an e
202c0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
202d0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
202e0 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
202f0 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74  N_READWRITE]</dt
20300 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
20310 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
20320 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
20330 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69  writing if possi
20340 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a  ble, or reading.
20350 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66  ** only if the f
20360 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f  ile is write pro
20370 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70  tected by the op
20380 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
20390 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61   In either.** ca
203a0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
203b0 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69  must already exi
203c0 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e  st, otherwise an
203d0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
203e0 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
203f0 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
20400 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
20410 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
20420 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  EATE]</dt>.** <d
20430 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
20440 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
20450 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
20460 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64  , and is created
20470 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e   if.** it does n
20480 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ot already exist
20490 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65  . This is the be
204a0 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61  havior that is a
204b0 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a  lways used for.*
204c0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
204d0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
204e0 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  n16().</dd>)^.**
204f0 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20   </dl>.**.** If 
20500 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
20510 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
20520 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e  n_v2() is not on
20530 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62  e of the.** comb
20540 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61  inations shown a
20550 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  bove optionally 
20560 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74  combined with ot
20570 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  her.** [SQLITE_O
20580 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53  PEN_READONLY | S
20590 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74  QLITE_OPEN_* bit
205a0 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62  s].** then the b
205b0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
205c0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ined..**.** ^If 
205d0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
205e0 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  _NOMUTEX] flag i
205f0 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20  s set, then the 
20600 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
20610 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20  ion.** opens in 
20620 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  the multi-thread
20630 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
20640 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  ] as long as the
20650 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a   single-thread.*
20660 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62  * mode has not b
20670 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69  een set at compi
20680 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
20690 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a  -time.  ^If the.
206a0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
206b0 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20  FULLMUTEX] flag 
206c0 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20  is set then the 
206d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
206e0 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20  ion opens.** in 
206f0 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
20700 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
20710 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68  unless single-th
20720 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76  read was.** prev
20730 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20  iously selected 
20740 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
20750 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a  or start-time..*
20760 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
20770 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
20780 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
20790 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
207a0 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c  tion to be.** el
207b0 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73  igible to use [s
207c0 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
207d0 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ], regardless of
207e0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
207f0 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20  shared.** cache 
20800 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67  is enabled using
20810 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
20820 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d  _shared_cache()]
20830 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49  .  ^The.** [SQLI
20840 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
20850 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
20860 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
20870 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74  onnection to not
20880 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20  .** participate 
20890 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  in [shared cache
208a0 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69   mode] even if i
208b0 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  t is enabled..**
208c0 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
208d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
208e0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
208f0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
20900 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
20910 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
20920 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61  efines the opera
20930 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
20940 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68  rface that.** th
20950 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
20960 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64  onnection should
20970 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66   use.  ^If the f
20980 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
20990 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  is.** a NULL poi
209a0 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65  nter then the de
209b0 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
209c0 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73  fs] object is us
209d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
209e0 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a  e filename is ":
209f0 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61  memory:", then a
20a00 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
20a10 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  ary in-memory da
20a20 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65  tabase.** is cre
20a30 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e  ated for the con
20a40 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20  nection.  ^This 
20a50 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
20a60 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77  se will vanish w
20a70 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  hen.** the datab
20a80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
20a90 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72  s closed.  Futur
20aa0 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
20ab0 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61  Lite might.** ma
20ac0 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69  ke use of additi
20ad0 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c  onal special fil
20ae0 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69  enames that begi
20af0 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63  n with the ":" c
20b00 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20  haracter..** It 
20b10 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
20b20 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62  hat when a datab
20b30 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74  ase filename act
20b40 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e  ually does begin
20b50 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63   with.** a ":" c
20b60 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f  haracter you sho
20b70 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66  uld prefix the f
20b80 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70  ilename with a p
20b90 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a  athname such as.
20ba0 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64  ** "./" to avoid
20bb0 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a   ambiguity..**.*
20bc0 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
20bd0 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73  me is an empty s
20be0 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72  tring, then a pr
20bf0 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
20c00 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61  .** on-disk data
20c10 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65  base will be cre
20c20 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69  ated.  ^This pri
20c30 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69  vate database wi
20c40 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74  ll be.** automat
20c50 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61  ically deleted a
20c60 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61  s soon as the da
20c70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
20c80 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
20c90 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
20ca0 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70  es in sqlite3_op
20cb0 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46  en()]] <h3>URI F
20cc0 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a  ilenames</h3>.**
20cd0 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c  .** ^If [URI fil
20ce0 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74  ename] interpret
20cf0 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
20d00 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61  , and the filena
20d10 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62  me argument.** b
20d20 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65  egins with "file
20d30 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c  :", then the fil
20d40 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72  ename is interpr
20d50 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e  eted as a URI. ^
20d60 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  URI.** filename 
20d70 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
20d80 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
20d90 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
20da0 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65  I] flag is.** se
20db0 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20  t in the fourth 
20dc0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
20dd0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f  te3_open_v2(), o
20de0 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62  r if it has.** b
20df0 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62  een enabled glob
20e00 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b  ally using the [
20e10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
20e20 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74  I] option with t
20e30 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
20e40 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20  onfig()] method 
20e50 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  or by the [SQLIT
20e60 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69  E_USE_URI] compi
20e70 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a  le-time option..
20e80 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20  ** As of SQLite 
20e90 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55  version 3.7.7, U
20ea0 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65  RI filename inte
20eb0 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75  rpretation is tu
20ec0 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64  rned off.** by d
20ed0 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75  efault, but futu
20ee0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
20ef0 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62  QLite might enab
20f00 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a  le URI filename.
20f10 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  ** interpretatio
20f20 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53  n by default.  S
20f30 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ee "[URI filenam
20f40 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f  es]" for additio
20f50 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
20f60 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69  on..**.** URI fi
20f70 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73  lenames are pars
20f80 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  ed according to 
20f90 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68  RFC 3986. ^If th
20fa0 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61  e URI contains a
20fb0 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20  n.** authority, 
20fc0 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20  then it must be 
20fd0 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20  either an empty 
20fe0 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74  string or the st
20ff0 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68  ring .** "localh
21000 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75  ost". ^If the au
21010 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61  thority is not a
21020 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
21030 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61  r "localhost", a
21040 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72  n .** error is r
21050 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63  eturned to the c
21060 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67  aller. ^The frag
21070 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  ment component o
21080 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20  f a URI, if .** 
21090 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f  present, is igno
210a0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  red..**.** ^SQLi
210b0 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74 68  te uses the path
210c0 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68   component of th
210d0 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d  e URI as the nam
210e0 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69  e of the disk fi
210f0 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74  le.** which cont
21100 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 73  ains the databas
21110 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  e. ^If the path 
21120 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f  begins with a '/
21130 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a  ' character, .**
21140 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65   then it is inte
21150 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 62  rpreted as an ab
21160 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66  solute path. ^If
21170 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e   the path does n
21180 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74  ot begin .** wit
21190 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67  h a '/' (meaning
211a0 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
211b0 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f  ity section is o
211c0 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
211d0 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  URI).** then the
211e0 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 72   path is interpr
211f0 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 69  eted as a relati
21200 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e  ve path. .** ^On
21210 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69   windows, the fi
21220 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  rst component of
21230 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
21240 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65  h .** is a drive
21250 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28   specification (
21260 65 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a  e.g. "C:")..**.*
21270 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65  * [[core URI que
21280 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a  ry parameters]].
21290 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d  ** The query com
212a0 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
212b0 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61  may contain para
212c0 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20  meters that are 
212d0 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65  interpreted.** e
212e0 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20  ither by SQLite 
212f0 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20  itself, or by a 
21300 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46  [VFS | custom VF
21310 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
21320 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  ]..** SQLite int
21330 65 72 70 72 65 74 73 20 74 68 65 20 66 6f 6c 6c  erprets the foll
21340 6f 77 69 6e 67 20 74 68 72 65 65 20 71 75 65 72  owing three quer
21350 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a  y parameters:.**
21360 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
21370 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e  i> <b>vfs</b>: ^
21380 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65  The "vfs" parame
21390 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20  ter may be used 
213a0 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e  to specify the n
213b0 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20  ame of.**     a 
213c0 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20  VFS object that 
213d0 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65  provides the ope
213e0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
213f0 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f  terface that sho
21400 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73  uld.**     be us
21410 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ed to access the
21420 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f   database file o
21430 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73  n disk. ^If this
21440 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
21450 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74  o.**     an empt
21460 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66  y string the def
21470 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20  ault VFS object 
21480 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66  is used. ^Specif
21490 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a  ying an unknown.
214a0 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e  **     VFS is an
214b0 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69   error. ^If sqli
214c0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
214d0 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66   used and the vf
214e0 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  s option is.**  
214f0 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e     present, then
21500 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69   the VFS specifi
21510 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e  ed by the option
21520 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63   takes precedenc
21530 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68  e over.**     th
21540 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
21550 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  s the fourth par
21560 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
21570 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
21580 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64  **   <li> <b>mod
21590 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64  e</b>: ^(The mod
215a0 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
215b0 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
215c0 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20   "ro", "rw",.** 
215d0 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d      "rwc", or "m
215e0 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69  emory". Attempti
215f0 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20  ng to set it to 
21600 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20  any other value 
21610 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72  is.**     an err
21620 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49  or)^. .**     ^I
21630 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66  f "ro" is specif
21640 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61  ied, then the da
21650 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
21660 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a   for read-only .
21670 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a  **     access, j
21680 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53  ust as if the [S
21690 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
216a0 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65  NLY] flag had be
216b0 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a  en set in the .*
216c0 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75  *     third argu
216d0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
216e0 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74  open_v2(). ^If t
216f0 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
21700 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20  s set to .**    
21710 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20   "rw", then the 
21720 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
21730 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74  ed for read-writ
21740 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74  e (but not creat
21750 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  e) .**     acces
21760 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f  s, as if SQLITE_
21770 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28  OPEN_READWRITE (
21780 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f  but not SQLITE_O
21790 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20  PEN_CREATE) had 
217a0 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74  .**     been set
217b0 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69  . ^Value "rwc" i
217c0 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
217d0 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a  setting both .**
217e0 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
217f0 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53  _READWRITE and S
21800 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
21810 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65  E.  ^If the mode
21820 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20   option is.**   
21830 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79    set to "memory
21840 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69  " then a pure [i
21850 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
21860 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72 65  e] that never re
21870 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72  ads.**     or wr
21880 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69  ites from disk i
21890 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61  s used. ^It is a
218a0 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69  n error to speci
218b0 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a  fy a value for.*
218c0 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70  *     the mode p
218d0 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73  arameter that is
218e0 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76   less restrictiv
218f0 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63  e than that spec
21900 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  ified by.**     
21910 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 64  the flags passed
21920 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61   in the third pa
21930 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
21940 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
21950 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61  .**   <li> <b>ca
21960 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61  che</b>: ^The ca
21970 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  che parameter ma
21980 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
21990 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a  er "shared" or.*
219a0 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e  *     "private".
219b0 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20   ^Setting it to 
219c0 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69  "shared" is equi
219d0 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
219e0 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c  g the.**     SQL
219f0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
21a00 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20  ACHE bit in the 
21a10 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70  flags argument p
21a20 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20  assed to.**     
21a30 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
21a40 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20  ). ^Setting the 
21a50 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
21a60 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20  to "private" is 
21a70 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65  .**     equivale
21a80 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
21a90 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52  e SQLITE_OPEN_PR
21aa0 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a  IVATECACHE bit..
21ab0 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74  **     ^If sqlit
21ac0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
21ad0 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61  used and the "ca
21ae0 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69  che" parameter i
21af0 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20  s present in.** 
21b00 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61      a URI filena
21b10 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76  me, its value ov
21b20 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61  errides any beha
21b30 76 69 6f 72 20 72 65 71 75 65 73 74 65 64 20 62  vior requested b
21b40 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20  y setting.**    
21b50 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
21b60 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c  VATECACHE or SQL
21b70 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
21b80 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f  ACHE flag..** </
21b90 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69  ul>.**.** ^Speci
21ba0 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e  fying an unknown
21bb0 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
21bc0 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
21bd0 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f  t of a URI is no
21be0 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20  t an.** error.  
21bf0 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
21c00 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
21c10 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74  understand addit
21c20 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70  ional query.** p
21c30 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20  arameters.  See 
21c40 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  "[query paramete
21c50 72 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20  rs with special 
21c60 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74  meaning to SQLit
21c70 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74  e]" for.** addit
21c80 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
21c90 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  n..**.** [[URI f
21ca0 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
21cb0 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e  ]] <h3>URI filen
21cc0 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33  ame examples</h3
21cd0 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  >.**.** <table b
21ce0 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d  order="1" align=
21cf0 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69  center cellpaddi
21d00 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ng=5>.** <tr><th
21d10 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  > URI filenames 
21d20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20  <th> Results.** 
21d30 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
21d40 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20  ta.db <td> .**  
21d50 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
21d60 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
21d70 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  in the current d
21d80 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72  irectory..** <tr
21d90 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65  ><td> file:/home
21da0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72  /fred/data.db<br
21db0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69  >.**          fi
21dc0 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f  le:///home/fred/
21dd0 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a  data.db <br> .**
21de0 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
21df0 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f  /localhost/home/
21e00 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
21e10 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  > <td> .**      
21e20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74      Open the dat
21e30 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d  abase file "/hom
21e40 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e  e/fred/data.db".
21e50 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
21e60 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d  e://darkstar/hom
21e70 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
21e80 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
21e90 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b   An error. "dark
21ea0 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72  star" is not a r
21eb0 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72  ecognized author
21ec0 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20  ity..** <tr><td 
21ed0 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61  style="white-spa
21ee0 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20  ce:nowrap"> .** 
21ef0 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
21f00 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30  /C:/Documents%20
21f10 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66  and%20Settings/f
21f20 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61  red/Desktop/data
21f30 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20  .db.**     <td> 
21f40 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70  Windows only: Op
21f50 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74  en the file "dat
21f60 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20  a.db" on fred's 
21f70 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65  desktop on drive
21f80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e  .**          C:.
21f90 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25   Note that the %
21fa0 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74  20 escaping in t
21fb0 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e  his example is n
21fc0 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20  ot strictly .** 
21fd0 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61           necessa
21fe0 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61  ry - space chara
21ff0 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65  cters can be use
22000 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20  d literally.**  
22010 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66          in URI f
22020 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72  ilenames..** <tr
22030 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
22040 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65  db?mode=ro&cache
22050 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a  =private <td> .*
22060 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
22070 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69  file "data.db" i
22080 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69  n the current di
22090 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64  rectory for read
220a0 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a  -only access..**
220b0 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64            Regard
220c0 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
220d0 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61  or not shared-ca
220e0 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62  che mode is enab
220f0 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  led by.**       
22100 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20     default, use 
22110 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e  a private cache.
22120 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
22130 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  e:/home/fred/dat
22140 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f  a.db?vfs=unix-no
22150 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20 20  lock <td>.**    
22160 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20        Open file 
22170 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  "/home/fred/data
22180 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73 70  .db". Use the sp
22190 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d  ecial VFS "unix-
221a0 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e  nolock"..** <tr>
221b0 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
221c0 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20  b?mode=readonly 
221d0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
221e0 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61    An error. "rea
221f0 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20  donly" is not a 
22200 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72  valid option for
22210 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61   the "mode" para
22220 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c  meter..** </tabl
22230 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65  e>.**.** ^URI he
22240 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
22250 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29   sequences (%HH)
22260 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77   are supported w
22270 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61  ithin the path a
22280 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70  nd.** query comp
22290 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e  onents of a URI.
222a0 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65   A hexadecimal e
222b0 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63  scape sequence c
222c0 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20  onsists of a.** 
222d0 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22  percent sign - "
222e0 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79  %" - followed by
222f0 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78   exactly two hex
22300 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20  adecimal digits 
22310 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61  .** specifying a
22320 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e  n octet value. ^
22330 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20  Before the path 
22340 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  or query compone
22350 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20  nts of a.** URI 
22360 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74  filename are int
22370 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61  erpreted, they a
22380 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67  re encoded using
22390 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a   UTF-8 and all .
223a0 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65  ** hexadecimal e
223b0 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20  scape sequences 
223c0 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69  replaced by a si
223d0 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69  ngle byte contai
223e0 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72  ning the.** corr
223f0 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e  esponding octet.
22400 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73   If this process
22410 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e   generates an in
22420 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f  valid UTF-8 enco
22430 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73  ding,.** the res
22440 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
22450 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ed..**.** <b>Not
22460 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65  e to Windows use
22470 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63  rs:</b>  The enc
22480 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74  oding used for t
22490 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
224a0 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  ment.** of sqlit
224b0 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
224c0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
224d0 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e  must be UTF-8, n
224e0 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63  ot whatever.** c
224f0 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65  odepage is curre
22500 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46  ntly defined.  F
22510 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e  ilenames contain
22520 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61  ing internationa
22530 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  l.** characters 
22540 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
22550 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72  d to UTF-8 prior
22560 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d   to passing them
22570 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   into.** sqlite3
22580 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
22590 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
225a0 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
225b0 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75  indows Runtime u
225c0 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74  sers:</b>  The t
225d0 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f  emporary directo
225e0 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a  ry must be set.*
225f0 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  * prior to calli
22600 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ng sqlite3_open(
22610 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
22620 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69  n_v2().  Otherwi
22630 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66  se, various.** f
22640 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71  eatures that req
22650 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20  uire the use of 
22660 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20  temporary files 
22670 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20  may fail..**.** 
22680 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
22690 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
226a0 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  y].*/.int sqlite
226b0 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20  3_open(.  const 
226c0 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
226d0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
226e0 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
226f0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
22700 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
22710 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
22720 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
22730 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20  qlite3_open16(. 
22740 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c   const void *fil
22750 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
22760 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
22770 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69  TF-16) */.  sqli
22780 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
22790 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
227a0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
227b0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
227c0 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20  pen_v2(.  const 
227d0 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
227e0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
227f0 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
22800 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
22810 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db,         /* O
22820 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
22830 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c  ndle */.  int fl
22840 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20  ags,            
22850 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20    /* Flags */.  
22860 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73  const char *zVfs
22870 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
22880 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f  of VFS module to
22890 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   use */.);../*.*
228a0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
228b0 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52  in Values For UR
228c0 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a  I Parameters.**.
228d0 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 74 69  ** These are uti
228e0 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75  lity routines, u
228f0 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70  seful to VFS imp
22900 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68  lementations, th
22910 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73  at check.** to s
22920 65 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65  ee if a database
22930 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 20   file was a URI 
22940 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61  that contained a
22950 20 73 70 65 63 69 66 69 63 20 71 75 65 72 79 20   specific query 
22960 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61  .** parameter, a
22970 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73  nd if so obtains
22980 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
22990 61 74 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  at query paramet
229a0 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69  er..**.** If F i
229b0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
229c0 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20  ilename pointer 
229d0 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20  passed into the 
229e0 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f  xOpen() method o
229f0 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c  f .** a VFS impl
22a00 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20  ementation when 
22a10 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  the flags parame
22a20 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68  ter to xOpen() h
22a30 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f  as one or .** mo
22a40 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  re of the [SQLIT
22a50 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b  E_OPEN_URI] or [
22a60 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
22a70 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e  _DB] bits set an
22a80 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61  d.** P is the na
22a90 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  me of the query 
22aa0 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a  parameter, then.
22ab0 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  ** sqlite3_uri_p
22ac0 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
22ad0 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20  turns the value 
22ae0 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61  of the P.** para
22af0 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 69 73  meter if it exis
22b00 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ts or a NULL poi
22b10 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e  nter if P does n
22b20 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 20 0a  ot appear as a .
22b30 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ** query paramet
22b40 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69  er on F.  If P i
22b50 73 20 61 20 71 75 65 72 79 20 70 61 72 61 6d 65  s a query parame
22b60 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20  ter of F.** has 
22b70 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75  no explicit valu
22b80 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  e, then sqlite3_
22b90 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c  uri_parameter(F,
22ba0 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  P) returns.** a 
22bb0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d  pointer to an em
22bc0 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  pty string..**.*
22bd0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72  * The sqlite3_ur
22be0 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
22bf0 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73   routine assumes
22c00 20 74 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f   that P is a boo
22c10 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65  lean.** paramete
22c20 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72  r and returns tr
22c30 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20  ue (1) or false 
22c40 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  (0) according to
22c50 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66   the value.** of
22c60 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33   P.  The sqlite3
22c70 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
22c80 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ,B) routine retu
22c90 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 66 20  rns true (1) if 
22ca0 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  the.** value of 
22cb0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
22cc0 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73  P is one of "yes
22cd0 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f  ", "true", or "o
22ce0 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73  n" in any.** cas
22cf0 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75  e or if the valu
22d00 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  e begins with a 
22d10 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e  non-zero number.
22d20 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65    The .** sqlite
22d30 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
22d40 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65  P,B) routines re
22d50 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20  turns false (0) 
22d60 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a  if the value of.
22d70 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ** query paramet
22d80 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22  er P is one of "
22d90 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72  no", "false", or
22da0 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61   "off" in any ca
22db0 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20  se or.** if the 
22dc0 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74  value begins wit
22dd0 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f  h a numeric zero
22de0 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61  .  If P is not a
22df0 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65   query.** parame
22e00 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74  ter on F or if t
22e10 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73  he value of P is
22e20 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20   does not match 
22e30 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62  any of the.** ab
22e40 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ove, then sqlite
22e50 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
22e60 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42 21  P,B) returns (B!
22e70 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  =0)..**.** The s
22e80 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34  qlite3_uri_int64
22e90 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20  (F,P,D) routine 
22ea0 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c  converts the val
22eb0 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a  ue of P into a.*
22ec0 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  * 64-bit signed 
22ed0 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74 75  integer and retu
22ee0 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65 72  rns that integer
22ef0 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73  , or D if P does
22f00 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20   not.** exist.  
22f10 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  If the value of 
22f20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f  P is something o
22f30 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74  ther than an int
22f40 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65  eger, then.** ze
22f50 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  ro is returned..
22f60 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61  ** .** If F is a
22f70 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74   NULL pointer, t
22f80 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
22f90 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
22fa0 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a  eturns NULL and.
22fb0 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  ** sqlite3_uri_b
22fc0 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65  oolean(F,P,B) re
22fd0 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69  turns B.  If F i
22fe0 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69  s not a NULL poi
22ff0 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e  nter and.** is n
23000 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69  ot a database fi
23010 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e  le pathname poin
23020 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  ter that SQLite 
23030 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20  passed into the 
23040 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74  xOpen.** VFS met
23050 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65  hod, then the be
23060 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72  havior of this r
23070 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69  outine is undefi
23080 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
23090 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  .** undesirable.
230a0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
230b0 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
230c0 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72  meter(const char
230d0 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e   *zFilename, con
230e0 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29  st char *zParam)
230f0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72  ;.int sqlite3_ur
23100 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20  i_boolean(const 
23110 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e  char *zFile, con
23120 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c  st char *zParam,
23130 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a   int bDefault);.
23140 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
23150 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28  lite3_uri_int64(
23160 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e  const char*, con
23170 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65  st char*, sqlite
23180 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a  3_int64);.../*.*
23190 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f  * CAPI3REF: Erro
231a0 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73  r Codes And Mess
231b0 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ages.**.** ^The 
231c0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
231d0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
231e0 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20  rns the numeric 
231f0 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
23200 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
23210 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74  sult code] for t
23220 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66  he most recent f
23230 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20  ailed sqlite3_* 
23240 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f  API call.** asso
23250 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64  ciated with a [d
23260 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
23270 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20  on]. If a prior 
23280 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a  API call failed.
23290 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20  ** but the most 
232a0 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20  recent API call 
232b0 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72  succeeded, the r
232c0 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
232d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63  .** sqlite3_errc
232e0 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ode() is undefin
232f0 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
23300 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
23310 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  de().** interfac
23320 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78  e is the same ex
23330 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77  cept that it alw
23340 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
23350 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
23360 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20  sult code] even 
23370 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65  when extended re
23380 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a  sult codes are.*
23390 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  * disabled..**.*
233a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
233b0 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69  rrmsg() and sqli
233c0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72  te3_errmsg16() r
233d0 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
233e0 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74  nguage.** text t
233f0 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
23400 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68  e error, as eith
23410 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
23420 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
23430 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
23440 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
23450 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
23460 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
23470 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  lly..** The appl
23480 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ication does not
23490 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61   need to worry a
234a0 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65  bout freeing the
234b0 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65   result..** Howe
234c0 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73  ver, the error s
234d0 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f  tring might be o
234e0 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65  verwritten or de
234f0 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20  allocated by.** 
23500 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
23510 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   to other SQLite
23520 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
23530 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  ions.)^.**.** ^T
23540 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74  he sqlite3_errst
23550 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  r() interface re
23560 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73  turns the Englis
23570 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a  h-language text.
23580 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69 62 65  ** that describe
23590 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f  s the [result co
235a0 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a  de], as UTF-8..*
235b0 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  * ^(Memory to ho
235c0 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
235d0 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
235e0 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
235f0 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f  y.** and must no
23600 74 20 62 65 20 66 72 65 65 64 20 62 79 20 74 68  t be freed by th
23610 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e  e application)^.
23620 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
23630 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
23640 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69  ading mode] is i
23650 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20  n use, it might 
23660 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74  be the.** case t
23670 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72  hat a second err
23680 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73  or occurs on a s
23690 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69  eparate thread i
236a0 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  n between.** the
236b0 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72   time of the fir
236c0 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65  st error and the
236d0 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69   call to these i
236e0 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68  nterfaces..** Wh
236f0 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c  en that happens,
23700 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f   the second erro
23710 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74  r will be report
23720 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a  ed since these.*
23730 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77  * interfaces alw
23740 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d  ays report the m
23750 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c  ost recent resul
23760 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20  t.  To avoid.** 
23770 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61  this, each threa
23780 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63  d can obtain exc
23790 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68  lusive use of th
237a0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
237b0 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20  ection] D.** by 
237c0 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
237d0 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b  3_mutex_enter]([
237e0 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
237f0 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67  ](D)) before beg
23800 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65  inning.** to use
23810 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20   D and invoking 
23820 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c  [sqlite3_mutex_l
23830 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64  eave]([sqlite3_d
23840 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74  b_mutex](D)) aft
23850 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20  er.** all calls 
23860 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  to the interface
23870 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72  s listed here ar
23880 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a  e completed..**.
23890 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61  ** If an interfa
238a0 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51  ce fails with SQ
238b0 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61  LITE_MISUSE, tha
238c0 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65  t means the inte
238d0 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76  rface.** was inv
238e0 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  oked incorrectly
238f0 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
23900 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61  ion.  In that ca
23910 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  se, the.** error
23920 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
23930 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74  e may or may not
23940 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20   be set..*/.int 
23950 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
23960 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e  sqlite3 *db);.in
23970 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
23980 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  ed_errcode(sqlit
23990 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63  e3 *db);.const c
239a0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
239b0 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63  msg(sqlite3*);.c
239c0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
239d0 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69  e3_errmsg16(sqli
239e0 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 61  te3*);.const cha
239f0 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 73 74  r *sqlite3_errst
23a00 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  r(int);../*.** C
23a10 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61  API3REF: SQL Sta
23a20 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
23a30 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70   KEYWORDS: {prep
23a40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20  ared statement} 
23a50 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
23a60 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  ents}.**.** An i
23a70 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
23a80 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
23a90 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73  s a single SQL s
23aa0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69  tatement..** Thi
23ab0 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69  s object is vari
23ac0 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61  ously known as a
23ad0 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74 65   "prepared state
23ae0 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63  ment" or a.** "c
23af0 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74  ompiled SQL stat
23b00 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79  ement" or simply
23b10 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74   as a "statement
23b20 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66  "..**.** The lif
23b30 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74  e of a statement
23b40 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d   object goes som
23b50 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73  ething like this
23b60 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
23b70 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20  <li> Create the 
23b80 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
23b90 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
23ba0 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64  ()] or a related
23bb0 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f  .**      functio
23bc0 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20  n..** <li> Bind 
23bd0 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20  values to [host 
23be0 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e  parameters] usin
23bf0 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
23c00 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69  nd_*().**      i
23c10 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c  nterfaces..** <l
23c20 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62  i> Run the SQL b
23c30 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
23c40 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f  e3_step()] one o
23c50 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
23c60 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20   <li> Reset the 
23c70 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
23c80 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
23c90 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a  ] then go back.*
23ca0 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32  *      to step 2
23cb0 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20  .  Do this zero 
23cc0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
23cd0 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74  * <li> Destroy t
23ce0 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
23cf0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
23d00 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  e()]..** </ol>.*
23d10 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f  *.** Refer to do
23d20 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69  cumentation on i
23d30 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64  ndividual method
23d40 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69  s above for addi
23d50 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
23d60 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  ation..*/.typede
23d70 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
23d80 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74  _stmt sqlite3_st
23d90 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  mt;../*.** CAPI3
23da0 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69  REF: Run-time Li
23db0 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  mits.**.** ^(Thi
23dc0 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
23dd0 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76  ws the size of v
23de0 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74  arious construct
23df0 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a  s to be limited.
23e00 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69  ** on a connecti
23e10 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e  on by connection
23e20 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72   basis.  The fir
23e30 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
23e40 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
23e50 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f   connection] who
23e60 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62  se limit is to b
23e70 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64  e set or queried
23e80 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
23e90 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e   parameter is on
23ea0 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20  e of the [limit 
23eb0 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74  categories] that
23ec0 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61   define a.** cla
23ed0 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73  ss of constructs
23ee0 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69   to be size limi
23ef0 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20  ted.  The third 
23f00 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
23f10 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f  .** new limit fo
23f20 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74  r that construct
23f30 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  .)^.**.** ^If th
23f40 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61  e new limit is a
23f50 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72   negative number
23f60 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75  , the limit is u
23f70 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46  nchanged..** ^(F
23f80 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61  or each limit ca
23f90 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49  tegory SQLITE_LI
23fa0 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20  MIT_<i>NAME</i> 
23fb0 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b  there is a .** [
23fc0 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70  limits | hard up
23fd0 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65  per bound].** se
23fe0 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
23ff0 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f 63  e by a C preproc
24000 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c  essor macro call
24010 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  ed.** [limits | 
24020 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41  SQLITE_MAX_<i>NA
24030 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65  ME</i>]..** (The
24040 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68   "_LIMIT_" in th
24050 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65  e name is change
24060 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e  d to "_MAX_".))^
24070 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f  .** ^Attempts to
24080 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69   increase a limi
24090 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64  t above its hard
240a0 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65   upper bound are
240b0 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75  .** silently tru
240c0 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61  ncated to the ha
240d0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a  rd upper bound..
240e0 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73  **.** ^Regardles
240f0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
24100 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61  not the limit wa
24110 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a  s changed, the .
24120 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ** [sqlite3_limi
24130 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  t()] interface r
24140 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72  eturns the prior
24150 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69   value of the li
24160 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20  mit..** ^Hence, 
24170 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72 72  to find the curr
24180 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c  ent value of a l
24190 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68 61  imit without cha
241a0 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d  nging it,.** sim
241b0 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20  ply invoke this 
241c0 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20 74  interface with t
241d0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
241e0 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a  er set to -1..**
241f0 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d  .** Run-time lim
24200 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  its are intended
24210 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c   for use in appl
24220 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61  ications that ma
24230 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65  nage.** both the
24240 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20  ir own internal 
24250 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73  database and als
24260 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74  o databases that
24270 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a   are controlled.
24280 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20  ** by untrusted 
24290 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
242a0 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70  .  An example ap
242b0 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20  plication might 
242c0 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77  be a.** web brow
242d0 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73  ser that has its
242e0 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66   own databases f
242f0 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f  or storing histo
24300 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61  ry and.** separa
24310 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e  te databases con
24320 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53  trolled by JavaS
24330 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f  cript applicatio
24340 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a  ns downloaded.**
24350 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65   off the Interne
24360 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c  t.  The internal
24370 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62   databases can b
24380 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c  e given the.** l
24390 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69  arge, default li
243a0 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73  mits.  Databases
243b0 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65   managed by exte
243c0 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e  rnal sources can
243d0 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63  .** be given muc
243e0 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73  h smaller limits
243f0 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65   designed to pre
24400 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66  vent a denial of
24410 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61   service.** atta
24420 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20  ck.  Developers 
24430 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20  might also want 
24440 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69  to use the [sqli
24450 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
24460 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  er()].** interfa
24470 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f  ce to further co
24480 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20  ntrol untrusted 
24490 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  SQL.  The size o
244a0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
244b0 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20  * created by an 
244c0 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74  untrusted script
244d0 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65   can be containe
244e0 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  d using the.** [
244f0 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
24500 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20  [PRAGMA]..**.** 
24510 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d  New run-time lim
24520 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61  it categories ma
24530 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
24540 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
24550 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69  /.int sqlite3_li
24560 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  mit(sqlite3*, in
24570 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c  t id, int newVal
24580 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
24590 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d  EF: Run-Time Lim
245a0 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a  it Categories.**
245b0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69   KEYWORDS: {limi
245c0 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69  t category} {*li
245d0 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a  mit categories}.
245e0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
245f0 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72  tants define var
24600 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65  ious performance
24610 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20   limits.** that 
24620 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61  can be lowered a
24630 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67  t run-time using
24640 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
24650 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70  )]..** The synop
24660 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69  sis of the meani
24670 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f  ngs of the vario
24680 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f  us limits is sho
24690 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64  wn below..** Add
246a0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
246b0 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65  ion is available
246c0 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69   at [limits | Li
246d0 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e  mits in SQLite].
246e0 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b  .**.** <dl>.** [
246f0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
24700 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  NGTH]] ^(<dt>SQL
24710 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
24720 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
24730 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
24740 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42   any string or B
24750 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77  LOB or table row
24760 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29  , in bytes.<dd>)
24770 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
24780 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
24790 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
247a0 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
247b0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
247c0 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
247d0 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65   of an SQL state
247e0 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c  ment, in bytes.<
247f0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
24800 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
24810 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  MN]] ^(<dt>SQLIT
24820 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f  E_LIMIT_COLUMN</
24830 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
24840 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
24850 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61   columns in a ta
24860 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f  ble definition o
24870 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75  r in the.** resu
24880 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
24890 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69  ECT] or the maxi
248a0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
248b0 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65  lumns in an inde
248c0 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52  x.** or in an OR
248d0 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20  DER BY or GROUP 
248e0 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29  BY clause.</dd>)
248f0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
24900 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
24910 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
24920 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
24930 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
24940 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
24950 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65  of the parse tre
24960 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73  e on any express
24970 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
24980 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
24990 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
249a0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
249b0 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
249c0 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ELECT</dt>.** <d
249d0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
249e0 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
249f0 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45   a compound SELE
24a00 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64  CT statement.</d
24a10 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
24a20 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
24a30 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  P]] ^(<dt>SQLITE
24a40 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f  _LIMIT_VDBE_OP</
24a50 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
24a60 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
24a70 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e   instructions in
24a80 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69   a virtual machi
24a90 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73  ne program.** us
24aa0 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
24ab0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
24ac0 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73  .  This limit is
24ad0 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a   not currently.*
24ae0 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75  * enforced, thou
24af0 67 68 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  gh that might be
24b00 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66   added in some f
24b10 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
24b20 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e  .** SQLite.</dd>
24b30 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
24b40 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
24b50 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  _ARG]] ^(<dt>SQL
24b60 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
24b70 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  ON_ARG</dt>.** <
24b80 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
24b90 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
24ba0 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e  ts on a function
24bb0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
24bc0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  [SQLITE_LIMIT_AT
24bd0 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53  TACHED]] ^(<dt>S
24be0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
24bf0 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHED</dt>.** <dd
24c00 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
24c10 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c  ber of [ATTACH |
24c20 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
24c30 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  ses].)^</dd>.**.
24c40 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
24c50 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
24c60 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74  ENGTH]].** ^(<dt
24c70 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49  >SQLITE_LIMIT_LI
24c80 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
24c90 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
24ca0 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
24cb0 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20   of the pattern 
24cc0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
24cd0 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c  [LIKE] or.** [GL
24ce0 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f  OB] operators.</
24cf0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
24d00 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
24d10 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20  BLE_NUMBER]].** 
24d20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
24d30 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
24d40 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ER</dt>.** <dd>T
24d50 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78  he maximum index
24d60 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b   number of any [
24d70 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e  parameter] in an
24d80 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29   SQL statement.)
24d90 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
24da0 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
24db0 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EPTH]] ^(<dt>SQL
24dc0 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
24dd0 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
24de0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
24df0 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69  depth of recursi
24e00 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e  on for triggers.
24e10 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
24e20 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
24e30 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20  TE_LIMIT_LENGTH 
24e40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
24e50 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
24e60 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
24e70 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
24e80 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
24e90 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
24ea0 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  N               
24eb0 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
24ec0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
24ed0 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
24ee0 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
24ef0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
24f00 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20  POUND_SELECT    
24f10 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
24f20 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44   SQLITE_LIMIT_VD
24f30 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20  BE_OP           
24f40 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
24f50 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  e SQLITE_LIMIT_F
24f60 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20  UNCTION_ARG     
24f70 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
24f80 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
24f90 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20  ATTACHED        
24fa0 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
24fb0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
24fc0 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
24fd0 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65  NGTH       8.#de
24fe0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
24ff0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
25000 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  R           9.#d
25010 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
25020 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
25030 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a              10..
25040 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
25050 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c  Compiling An SQL
25060 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45   Statement.** KE
25070 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61  YWORDS: {SQL sta
25080 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d  tement compiler}
25090 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74  .**.** To execut
250a0 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20  e an SQL query, 
250b0 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65  it must first be
250c0 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61   compiled into a
250d0 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72   byte-code.** pr
250e0 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20  ogram using one 
250f0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
25100 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
25110 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62  st argument, "db
25120 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73  ", is a [databas
25130 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62  e connection] ob
25140 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  tained from a.**
25150 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
25160 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
25170 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
25180 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
25190 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  or.** [sqlite3_o
251a0 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64  pen16()].  The d
251b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
251c0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65  on must not have
251d0 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a   been closed..**
251e0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
251f0 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c  rgument, "zSql",
25200 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   is the statemen
25210 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
25220 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20  , encoded.** as 
25230 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
25240 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c  UTF-16.  The sql
25250 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61  ite3_prepare() a
25260 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
25270 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72  re_v2().** inter
25280 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c  faces use UTF-8,
25290 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
252a0 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c  pare16() and sql
252b0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
252c0 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31  2().** use UTF-1
252d0 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  6..**.** ^If the
252e0 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
252f0 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72  is less than zer
25300 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20  o, then zSql is 
25310 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a  read up to the.*
25320 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  * first zero ter
25330 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79  minator. ^If nBy
25340 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  te is non-negati
25350 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74  ve, then it is t
25360 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75  he maximum.** nu
25370 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72  mber of  bytes r
25380 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20  ead from zSql.  
25390 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e  ^When nByte is n
253a0 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
253b0 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20  .** zSql string 
253c0 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74  ends at either t
253d0 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20  he first '\000' 
253e0 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72  or '\u0000' char
253f0 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20  acter or.** the 
25400 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77  nByte-th byte, w
25410 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66  hichever comes f
25420 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c  irst. If the cal
25430 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61  ler knows.** tha
25440 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73  t the supplied s
25450 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72  tring is nul-ter
25460 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68  minated, then th
25470 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a  ere is a small.*
25480 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64  * performance ad
25490 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61  vantage to be ga
254a0 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20  ined by passing 
254b0 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74  an nByte paramet
254c0 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71  er that.** is eq
254d0 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65  ual to the numbe
254e0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
254f0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c  e input string <
25500 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a  i>including</i>.
25510 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69  ** the nul-termi
25520 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73 20 74  nator bytes as t
25530 68 69 73 20 73 61 76 65 73 20 53 51 4c 69 74 65  his saves SQLite
25540 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a   from having to.
25550 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f  ** make a copy o
25560 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  f the input stri
25570 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a  ng..**.** ^If pz
25580 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  Tail is not NULL
25590 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73   then *pzTail is
255a0 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
255b0 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65  o the first byte
255c0 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64  .** past the end
255d0 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51   of the first SQ
255e0 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  L statement in z
255f0 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74  Sql.  These rout
25600 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d  ines only.** com
25610 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73  pile the first s
25620 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
25630 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20  , so *pzTail is 
25640 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
25650 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73  .** what remains
25660 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a   uncompiled..**.
25670 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c  ** ^*ppStmt is l
25680 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20  eft pointing to 
25690 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70  a compiled [prep
256a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
256b0 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65  that can be.** e
256c0 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73  xecuted using [s
256d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20  qlite3_step()]. 
256e0 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e   ^If there is an
256f0 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20   error, *ppStmt 
25700 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c  is set.** to NUL
25710 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75  L.  ^If the inpu
25720 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20  t text contains 
25730 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69  no SQL (if the i
25740 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79  nput is an empty
25750 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20  .** string or a 
25760 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70  comment) then *p
25770 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20  pStmt is set to 
25780 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  NULL..** The cal
25790 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69  ling procedure i
257a0 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
257b0 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63  r deleting the c
257c0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73  ompiled.** SQL s
257d0 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
257e0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
257f0 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73  ()] after it has
25800 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
25810 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79  t..** ppStmt may
25820 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a   not be NULL..**
25830 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c  .** ^On success,
25840 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   the sqlite3_pre
25850 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66  pare() family of
25860 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
25870 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a   [SQLITE_OK];.**
25880 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   otherwise an [e
25890 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
258a0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
258b0 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
258c0 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74  e_v2() and sqlit
258d0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
258e0 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ) interfaces are
258f0 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20  .** recommended 
25900 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67  for all new prog
25910 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c  rams. The two ol
25920 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61  der interfaces a
25930 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66  re retained.** f
25940 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
25950 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20  patibility, but 
25960 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73  their use is dis
25970 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e  couraged..** ^In
25980 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
25990 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72  aces, the prepar
259a0 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
259b0 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64  that is returned
259c0 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
259d0 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e  tmt] object) con
259e0 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  tains a copy of 
259f0 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20  the.** original 
25a00 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63  SQL text. This c
25a10 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74  auses the [sqlit
25a20 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72  e3_step()] inter
25a30 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76  face to.** behav
25a40 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e  e differently in
25a50 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a   three ways:.**.
25a60 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a  ** <ol>.** <li>.
25a70 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62  ** ^If the datab
25a80 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
25a90 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72  es, instead of r
25aa0 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
25ab0 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a  _SCHEMA] as it.*
25ac0 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f  * always used to
25ad0 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74   do, [sqlite3_st
25ae0 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d  ep()] will autom
25af0 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
25b00 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74  le the SQL.** st
25b10 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20  atement and try 
25b20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e  to run it again.
25b30 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c   As many as [SQL
25b40 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52  ITE_MAX_SCHEMA_R
25b50 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73  ETRY].** retries
25b60 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f   will occur befo
25b70 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  re sqlite3_step(
25b80 29 20 67 69 76 65 73 20 75 70 20 61 6e 64 20 72  ) gives up and r
25b90 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e  eturns an error.
25ba0 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
25bb0 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e  <li>.** ^When an
25bc0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b   error occurs, [
25bd0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
25be0 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20  will return one 
25bf0 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a  of the detailed.
25c00 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ** [error codes]
25c10 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72   or [extended er
25c20 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68  ror codes].  ^Th
25c30 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
25c40 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73  r was that.** [s
25c50 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
25c60 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e  ould only return
25c70 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49   a generic [SQLI
25c80 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74  TE_ERROR] result
25c90 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65   code.** and the
25ca0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75   application wou
25cb0 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20  ld have to make 
25cc0 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f  a second call to
25cd0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
25ce0 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74  )].** in order t
25cf0 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72  o find the under
25d00 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74  lying cause of t
25d10 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68  he problem. With
25d20 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72   the "v2" prepar
25d30 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c  e.** interfaces,
25d40 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
25d50 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65  reason for the e
25d60 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
25d70 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
25d80 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
25d90 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65  >.** ^If the spe
25da0 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e  cific value boun
25db0 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20  d to [parameter 
25dc0 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  | host parameter
25dd0 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45  ] in the .** WHE
25de0 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20  RE clause might 
25df0 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68  influence the ch
25e00 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
25e10 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65  an for a stateme
25e20 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  nt,.** then the 
25e30 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62  statement will b
25e40 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
25e50 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69  recompiled, as i
25e60 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e  f there had been
25e70 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68   .** a schema ch
25e80 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72  ange, on the fir
25e90 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  st  [sqlite3_ste
25ea0 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77  p()] call follow
25eb0 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a  ing any change.*
25ec0 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
25ed0 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69  3_bind_text | bi
25ee0 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20  ndings] of that 
25ef0 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a  [parameter]. .**
25f00 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76   ^The specific v
25f10 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c  alue of WHERE-cl
25f20 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d  ause [parameter]
25f30 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65   might influence
25f40 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20   the .** choice 
25f50 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66  of query plan if
25f60 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
25f70 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20  s the left-hand 
25f80 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d  side of a [LIKE]
25f90 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70  .** or [GLOB] op
25fa0 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65  erator or if the
25fb0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f   parameter is co
25fc0 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64  mpared to an ind
25fd0 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  exed column.** a
25fe0 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45  nd the [SQLITE_E
25ff0 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d  NABLE_STAT3] com
26000 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
26010 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20   is enabled..** 
26020 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  </li>.** </ol>.*
26030 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  /.int sqlite3_pr
26040 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33  epare(.  sqlite3
26050 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
26060 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
26070 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
26080 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
26090 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
260a0 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
260b0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
260c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
260d0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
260e0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
260f0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
26100 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
26110 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
26120 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
26130 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
26140 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
26150 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
26160 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
26170 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
26180 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73  _prepare_v2(.  s
26190 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
261a0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
261b0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
261c0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
261d0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
261e0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
261f0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
26200 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
26210 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
26220 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
26230 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
26240 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
26250 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
26260 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
26270 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
26280 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
26290 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
262a0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
262b0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
262c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
262d0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
262e0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
262f0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
26300 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
26310 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
26320 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
26330 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
26340 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
26350 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
26360 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
26370 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
26380 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
26390 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
263a0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
263b0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
263c0 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
263d0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
263e0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
263f0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
26400 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
26410 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c  pare16_v2(.  sql
26420 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
26430 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
26440 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
26450 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
26460 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
26470 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
26480 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
26490 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
264a0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
264b0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
264c0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
264d0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
264e0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
264f0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
26500 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
26510 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
26520 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
26530 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
26540 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  Sql */.);../*.**
26550 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69   CAPI3REF: Retri
26560 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20  eving Statement 
26570 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  SQL.**.** ^This 
26580 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
26590 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76   used to retriev
265a0 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f  e a saved copy o
265b0 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a  f the original.*
265c0 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20  * SQL text used 
265d0 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65  to create a [pre
265e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
265f0 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65   if that stateme
26600 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c  nt was.** compil
26610 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ed using either 
26620 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
26630 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
26640 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
26650 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  )]..*/.const cha
26660 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73  r *sqlite3_sql(s
26670 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
26680 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
26690 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
266a0 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
266b0 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44  ent Writes The D
266c0 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54  atabase.**.** ^T
266d0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
266e0 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65  readonly(X) inte
266f0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
26700 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
26710 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20  .** and only if 
26720 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
26730 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73  atement] X makes
26740 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67   no direct chang
26750 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e  es to.** the con
26760 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
26770 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a  base file..**.**
26780 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c   Note that [appl
26790 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
267a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f  SQL functions] o
267b0 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61  r.** [virtual ta
267c0 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e  bles] might chan
267d0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
267e0 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20  indirectly as a 
267f0 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a  side effect.  .*
26800 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
26810 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
26820 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e  on defines a fun
26830 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74  ction "eval()" t
26840 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73  hat .** calls [s
26850 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
26860 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  then the followi
26870 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
26880 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65   would.** change
26890 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
268a0 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d  le through side-
268b0 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c  effects:.**.** <
268c0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
268d0 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76  .**    SELECT ev
268e0 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20  al('DELETE FROM 
268f0 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a  t1') FROM t2;.**
26900 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
26910 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62  ote>.**.** But b
26920 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45  ecause the [SELE
26930 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  CT] statement do
26940 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
26950 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a  e database file.
26960 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c  ** directly, sql
26970 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
26980 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c  ly() would still
26990 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a   return true.)^.
269a0 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69  **.** ^Transacti
269b0 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65  on control state
269c0 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42  ments such as [B
269d0 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c  EGIN], [COMMIT],
269e0 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20   [ROLLBACK],.** 
269f0 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64  [SAVEPOINT], and
26a00 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65   [RELEASE] cause
26a10 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
26a20 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
26a30 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63  rn true,.** sinc
26a40 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73  e the statements
26a50 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e   themselves do n
26a60 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69  ot actually modi
26a70 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
26a80 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68  but.** rather th
26a90 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74  ey control the t
26aa0 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74  iming of when ot
26ab0 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d  her statements m
26ac0 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61  odify the .** da
26ad0 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41  tabase.  ^The [A
26ae0 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41  TTACH] and [DETA
26af0 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61  CH] statements a
26b00 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c  lso cause.** sql
26b10 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
26b20 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
26b30 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65  rue since, while
26b40 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74   those statement
26b50 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  s.** change the 
26b60 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66  configuration of
26b70 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
26b80 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20  ection, they do 
26b90 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61  not make .** cha
26ba0 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74  nges to the cont
26bb0 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62  ent of the datab
26bc0 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73  ase files on dis
26bd0 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  k..*/.int sqlite
26be0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
26bf0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
26c00 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
26c10 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
26c20 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53   If A Prepared S
26c30 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65  tatement Has Bee
26c40 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54  n Reset.**.** ^T
26c50 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
26c60 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63  busy(S) interfac
26c70 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
26c80 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65  non-zero) if the
26c90 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
26ca0 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62  atement] S has b
26cb0 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c  een stepped at l
26cc0 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20  east once using 
26cd0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
26ce0 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 6f  p(S)] but has no
26cf0 74 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74  t run to complet
26d00 69 6f 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e  ion and/or has n
26d10 6f 74 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65  ot .** been rese
26d20 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
26d30 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68  _reset(S)].  ^Th
26d40 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  e sqlite3_stmt_b
26d50 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66  usy(S).** interf
26d60 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73  ace returns fals
26d70 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c  e if S is a NULL
26d80 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20   pointer.  If S 
26d90 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c  is not a .** NUL
26da0 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73  L pointer and is
26db0 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74   not a pointer t
26dc0 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61  o a valid [prepa
26dd0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
26de0 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74  * object, then t
26df0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
26e00 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
26e10 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c  bably undesirabl
26e20 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  e..**.** This in
26e30 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
26e40 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69  sed in combinati
26e50 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74  on [sqlite3_next
26e60 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c  _stmt()].** to l
26e70 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72  ocate all prepar
26e80 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73  ed statements as
26e90 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
26ea0 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e  database .** con
26eb0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65  nection that are
26ec0 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e   in need of bein
26ed0 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 63  g reset.  This c
26ee0 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66  an be used,.** f
26ef0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64  or example, in d
26f00 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e  iagnostic routin
26f10 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72  es to search for
26f20 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74   prepared .** st
26f30 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72  atements that ar
26f40 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e  e holding a tran
26f50 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f  saction open..*/
26f60 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  .int sqlite3_stm
26f70 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73  t_busy(sqlite3_s
26f80 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
26f90 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61  PI3REF: Dynamica
26fa0 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20  lly Typed Value 
26fb0 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
26fc0 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73  DS: {protected s
26fd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75  qlite3_value} {u
26fe0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
26ff0 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20  e3_value}.**.** 
27000 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
27010 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
27020 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e  ject to represen
27030 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20  t all values.** 
27040 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72  that can be stor
27050 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65  ed in a database
27060 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75   table. SQLite u
27070 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69  ses dynamic typi
27080 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61  ng.** for the va
27090 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20  lues it stores. 
270a0 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20   ^Values stored 
270b0 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  in sqlite3_value
270c0 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20   objects.** can 
270d0 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f  be integers, flo
270e0 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
270f0 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f  es, strings, BLO
27100 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a  Bs, or NULL..**.
27110 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61  ** An sqlite3_va
27120 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62  lue object may b
27130 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63  e either "protec
27140 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65  ted" or "unprote
27150 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69  cted"..** Some i
27160 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
27170 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  e a protected sq
27180 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74  lite3_value.  Ot
27190 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  her interfaces.*
271a0 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69  * will accept ei
271b0 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64  ther a protected
271c0 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74   or an unprotect
271d0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
271e0 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72  ..** Every inter
271f0 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74  face that accept
27200 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  s sqlite3_value 
27210 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66  arguments specif
27220 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f  ies.** whether o
27230 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65  r not it require
27240 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  s a protected sq
27250 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a  lite3_value..**.
27260 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72  ** The terms "pr
27270 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e  otected" and "un
27280 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72  protected" refer
27290 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e   to whether or n
272a0 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73  ot.** a mutex is
272b0 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72   held.  An inter
272c0 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c  nal mutex is hel
272d0 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65  d for a protecte
272e0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
272f0 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f  ue object but no
27300 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
27310 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
27320 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
27330 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53  ue object.  If S
27340 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
27350 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74  d to be single-t
27360 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68  hreaded.** (with
27370 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
27380 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20  AFE=0] and with 
27390 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73  [sqlite3_threads
273a0 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67  afe()] returning
273b0 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c   0).** or if SQL
273c0 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e  ite is run in on
273d0 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74  e of reduced mut
273e0 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51  ex modes .** [SQ
273f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
27400 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51  LETHREAD] or [SQ
27410 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
27420 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e  ITHREAD].** then
27430 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73   there is no dis
27440 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
27450 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
27460 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
27470 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
27480 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e  cts and they can
27490 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68   be used interch
274a0 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76  angeably.  Howev
274b0 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d  er,.** for maxim
274c0 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c  um code portabil
274d0 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  ity it is recomm
274e0 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
274f0 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c  cations.** still
27500 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e   make the distin
27510 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
27520 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
27530 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
27540 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
27550 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73   even when not s
27560 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64  trictly required
27570 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
27580 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
27590 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73  ts that are pass
275a0 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73  ed as parameters
275b0 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70   into the.** imp
275c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
275d0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
275e0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
275f0 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64  s] are protected
27600 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
27610 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72  3_value object r
27620 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
27630 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
27640 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74  lue()] is unprot
27650 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74  ected..** Unprot
27660 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
27670 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20  lue objects may 
27680 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
27690 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  h.** [sqlite3_re
276a0 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e  sult_value()] an
276b0 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
276c0 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  value()]..** The
276d0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
276e0 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76  blob | sqlite3_v
276f0 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d  alue_type()] fam
27700 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ily of.** interf
27710 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f  aces require pro
27720 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
27730 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f  alue objects..*/
27740 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
27750 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  Mem sqlite3_valu
27760 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
27770 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  EF: SQL Function
27780 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a   Context Object.
27790 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78  **.** The contex
277a0 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51  t in which an SQ
277b0 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75  L function execu
277c0 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e  tes is stored in
277d0 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   an.** sqlite3_c
277e0 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20  ontext object.  
277f0 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ^A pointer to an
27800 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
27810 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c   object.** is al
27820 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d  ways first param
27830 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61  eter to [applica
27840 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
27850 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
27860 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  The application-
27870 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
27880 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
27890 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68  ion will pass th
278a0 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68  is.** pointer th
278b0 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73  rough into calls
278c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
278d0 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  ult_int | sqlite
278e0 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20  3_result()],.** 
278f0 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
27900 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b  te_context()], [
27910 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
27920 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  a()],.** [sqlite
27930 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
27940 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  dle()], [sqlite3
27950 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c  _get_auxdata()],
27960 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69  .** and/or [sqli
27970 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
27980 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
27990 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f  truct sqlite3_co
279a0 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f  ntext sqlite3_co
279b0 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ntext;../*.** CA
279c0 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20  PI3REF: Binding 
279d0 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72  Values To Prepar
279e0 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  ed Statements.**
279f0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74   KEYWORDS: {host
27a00 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73   parameter} {hos
27a10 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68  t parameters} {h
27a20 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
27a30 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  me}.** KEYWORDS:
27a40 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d   {SQL parameter}
27a50 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   {SQL parameters
27a60 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e  } {parameter bin
27a70 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  ding}.**.** ^(In
27a80 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
27a90 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f  nt text input to
27aa0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
27ab0 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20  e_v2()] and its 
27ac0 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74  variants,.** lit
27ad0 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70  erals may be rep
27ae0 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61  laced by a [para
27af0 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63  meter] that matc
27b00 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f  hes one of follo
27b10 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65  wing.** template
27b20 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
27b30 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e   <li>  ?.** <li>
27b40 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20    ?NNN.** <li>  
27b50 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56  :VVV.** <li>  @V
27b60 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56  VV.** <li>  $VVV
27b70 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
27b80 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73  In the templates
27b90 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72   above, NNN repr
27ba0 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65  esents an intege
27bb0 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e  r literal,.** an
27bc0 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73  d VVV represents
27bd0 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   an alphanumeric
27be0 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20   identifier.)^  
27bf0 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74  ^The values of t
27c00 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hese.** paramete
27c10 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20  rs (also called 
27c20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  "host parameter 
27c30 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70  names" or "SQL p
27c40 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63  arameters").** c
27c50 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20  an be set using 
27c60 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
27c70 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65  _*() routines de
27c80 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a  fined here..**.*
27c90 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
27ca0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
27cb0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
27cc0 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73  utines is always
27cd0 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
27ce0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
27cf0 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  mt] object retur
27d00 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c  ned from.** [sql
27d10 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
27d20 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
27d30 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ts..**.** ^The s
27d40 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
27d50 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
27d60 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  he SQL parameter
27d70 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e   to be set..** ^
27d80 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c  The leftmost SQL
27d90 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
27da0 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e  n index of 1.  ^
27db0 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61  When the same na
27dc0 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d  med.** SQL param
27dd0 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72  eter is used mor
27de0 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63  e than once, sec
27df0 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
27e00 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65  nt.** occurrence
27e10 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20  s have the same 
27e20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72  index as the fir
27e30 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a  st occurrence..*
27e40 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72  * ^The index for
27e50 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
27e60 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20  s can be looked 
27e70 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  up using the.** 
27e80 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
27e90 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
27ea0 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e   API if desired.
27eb0 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20    ^The index.** 
27ec0 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d  for "?NNN" param
27ed0 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c  eters is the val
27ee0 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54  ue of NNN..** ^T
27ef0 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73  he NNN value mus
27f00 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61  t be between 1 a
27f10 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  nd the [sqlite3_
27f20 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61  limit()].** para
27f30 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49  meter [SQLITE_LI
27f40 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
27f50 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61  BER] (default va
27f60 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a  lue: 999)..**.**
27f70 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
27f80 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75  ment is the valu
27f90 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65  e to bind to the
27fa0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
27fb0 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
27fc0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
27fd0 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72  3_bind_text() or
27fe0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
27ff0 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  xt16().** or sql
28000 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
28010 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
28020 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72  er then the four
28030 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  th parameter.** 
28040 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74  is ignored and t
28050 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73  he end result is
28060 20 74 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c   the same as sql
28070 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29  ite3_bind_null()
28080 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f  ..**.** ^(In tho
28090 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  se routines that
280a0 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61   have a fourth a
280b0 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c  rgument, its val
280c0 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
280d0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
280e0 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20  the parameter.  
280f0 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65  To be clear: the
28100 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
28110 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79   number of <u>by
28120 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76  tes</u> in the v
28130 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75  alue, not the nu
28140 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
28150 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65  rs.)^.** ^If the
28160 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
28170 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
28180 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  d_text() or sqli
28190 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
281a0 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  ).** is negative
281b0 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74  , then the lengt
281c0 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20  h of the string 
281d0 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  is.** the number
281e0 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20   of bytes up to 
281f0 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
28200 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66  erminator..** If
28210 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
28220 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
28230 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20  _bind_blob() is 
28240 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a  negative, then.*
28250 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  * the behavior i
28260 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
28270 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  If a non-negativ
28280 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
28290 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 20 74  er is provided t
282a0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
282b0 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ext().** or sqli
282c0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
282d0 29 20 74 68 65 6e 20 74 68 61 74 20 70 61 72 61  ) then that para
282e0 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 74 68  meter must be th
282f0 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a  e byte offset.**
28300 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74   where the NUL t
28310 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20  erminator would 
28320 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74  occur assuming t
28330 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e  he string were N
28340 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64  UL.** terminated
28350 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68  .  If any NUL ch
28360 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 20 61  aracters occur a
28370 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c  t byte offsets l
28380 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65  ess than .** the
28390 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f   value of the fo
283a0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
283b0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e  hen the resultin
283c0 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77  g string value w
283d0 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65  ill.** contain e
283e0 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54  mbedded NULs.  T
283f0 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70  he result of exp
28400 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69  ressions involvi
28410 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69  ng strings.** wi
28420 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  th embedded NULs
28430 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
28440 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20  *.** ^The fifth 
28450 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
28460 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c  te3_bind_blob(),
28470 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
28480 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c  xt(), and.** sql
28490 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
284a0 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74  () is a destruct
284b0 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f  or used to dispo
284c0 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
284d0 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65  r.** string afte
284e0 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e  r SQLite has fin
284f0 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20  ished with it.  
28500 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20  ^The destructor 
28510 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20  is called.** to 
28520 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
28530 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76  LOB or string ev
28540 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74  en if the call t
28550 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
28560 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  lob(),.** sqlite
28570 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 6f  3_bind_text(), o
28580 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
28590 65 78 74 31 36 28 29 20 66 61 69 6c 73 2e 20 20  ext16() fails.  
285a0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
285b0 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  h argument is.**
285c0 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c   the special val
285d0 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49  ue [SQLITE_STATI
285e0 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  C], then SQLite 
285f0 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
28600 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
28610 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e  is in static, un
28620 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e  managed space an
28630 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  d does not need 
28640 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20  to be freed..** 
28650 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
28660 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76  gument has the v
28670 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41  alue [SQLITE_TRA
28680 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a  NSIENT], then.**
28690 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74   SQLite makes it
286a0 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
286b0 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69  py of the data i
286c0 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f  mmediately, befo
286d0 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  re.** the sqlite
286e0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
286f0 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ne returns..**.*
28700 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
28710 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72  ind_zeroblob() r
28720 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42  outine binds a B
28730 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20  LOB of length N 
28740 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65  that.** is fille
28750 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20  d with zeroes.  
28760 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73  ^A zeroblob uses
28770 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20   a fixed amount 
28780 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75  of memory.** (ju
28790 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f  st an integer to
287a0 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20   hold its size) 
287b0 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e  while it is bein
287c0 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20  g processed..** 
287d0 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e  Zeroblobs are in
287e0 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20  tended to serve 
287f0 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  as placeholders 
28800 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a  for BLOBs whose.
28810 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61  ** content is la
28820 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e  ter written usin
28830 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c  g.** [sqlite3_bl
28840 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d  ob_open | increm
28850 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20  ental BLOB I/O] 
28860 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20  routines..** ^A 
28870 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66  negative value f
28880 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20  or the zeroblob 
28890 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72  results in a zer
288a0 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a  o-length BLOB..*
288b0 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20  *.** ^If any of 
288c0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
288d0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72  _*() routines ar
288e0 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  e called with a 
288f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
28900 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  for the [prepare
28910 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20  d statement] or 
28920 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20  with a prepared 
28930 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68  statement for wh
28940 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ich.** [sqlite3_
28950 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e  step()] has been
28960 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63   called more rec
28970 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69  ently than [sqli
28980 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a  te3_reset()],.**
28990 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77   then the call w
289a0 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
289b0 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20  TE_MISUSE].  If 
289c0 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  any sqlite3_bind
289d0 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69  _().** routine i
289e0 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70  s passed a [prep
289f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
28a00 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69  that has been fi
28a10 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20  nalized, the.** 
28a20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69  result is undefi
28a30 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
28a40 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20   harmful..**.** 
28a50 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f  ^Bindings are no
28a60 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65  t cleared by the
28a70 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
28a80 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e  )] routine..** ^
28a90 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65  Unbound paramete
28aa0 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  rs are interpret
28ab0 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ed as NULL..**.*
28ac0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
28ad0 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72  ind_* routines r
28ae0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
28af0 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20  ] on success or 
28b00 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  an.** [error cod
28b10 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67  e] if anything g
28b20 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b  oes wrong..** ^[
28b30 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73  SQLITE_RANGE] is
28b40 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
28b50 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e   parameter.** in
28b60 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
28b70 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e  nge.  ^[SQLITE_N
28b80 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65  OMEM] is returne
28b90 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61  d if malloc() fa
28ba0 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ils..**.** See a
28bb0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
28bc0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
28bd0 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nt()],.** [sqlit
28be0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
28bf0 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b  r_name()], and [
28c00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
28c10 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
28c20 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
28c30 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65  bind_blob(sqlite
28c40 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
28c50 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e  nst void*, int n
28c60 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
28c70 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
28c80 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ind_double(sqlit
28c90 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64  e3_stmt*, int, d
28ca0 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69  ouble);.int sqli
28cb0 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c  te3_bind_int(sql
28cc0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
28cd0 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
28ce0 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71  e3_bind_int64(sq
28cf0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
28d00 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
28d10 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
28d20 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  nd_null(sqlite3_
28d30 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74  stmt*, int);.int
28d40 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
28d50 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
28d60 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61  , int, const cha
28d70 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  r*, int n, void(
28d80 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
28d90 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
28da0 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
28db0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
28dc0 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
28dd0 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
28de0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
28df0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
28e00 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69   int, const sqli
28e10 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
28e20 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
28e30 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  roblob(sqlite3_s
28e40 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e  tmt*, int, int n
28e50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
28e60 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51  EF: Number Of SQ
28e70 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a  L Parameters.**.
28e80 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
28e90 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
28ea0 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
28eb0 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  of [SQL paramete
28ec0 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65  rs].** in a [pre
28ed0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
28ee0 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  .  SQL parameter
28ef0 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20  s are tokens of 
28f00 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c  the.** form "?",
28f10 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c   "?NNN", ":AAA",
28f20 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41   "$AAA", or "@AA
28f30 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73  A" that serve as
28f40 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73  .** placeholders
28f50 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74   for values that
28f60 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   are [sqlite3_bi
28f70 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d  nd_blob | bound]
28f80 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d  .** to the param
28f90 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72  eters at a later
28fa0 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   time..**.** ^(T
28fb0 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75  his routine actu
28fc0 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65  ally returns the
28fd0 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61   index of the la
28fe0 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74  rgest (rightmost
28ff0 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20  ).** parameter. 
29000 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78  For all forms ex
29010 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20  cept ?NNN, this 
29020 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20  will correspond 
29030 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  to the.** number
29040 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d   of unique param
29050 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d  eters.  If param
29060 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e  eters of the ?NN
29070 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c  N form are used,
29080 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65  .** there may be
29090 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73   gaps in the lis
290a0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  t.)^.**.** See a
290b0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
290c0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
290d0 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
290e0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
290f0 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
29100 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
29110 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
29120 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  x()]..*/.int sql
29130 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
29140 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ter_count(sqlite
29150 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
29160 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
29170 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65  Of A Host Parame
29180 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ter.**.** ^The s
29190 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
291a0 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20  meter_name(P,N) 
291b0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
291c0 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
291d0 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70   the N-th [SQL p
291e0 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
291f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29200 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51  ment] P..** ^(SQ
29210 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  L parameters of 
29220 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20  the form "?NNN" 
29230 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
29240 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
29250 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69   have a name whi
29260 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67  ch is the string
29270 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
29280 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
29290 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74  $AAA".** respect
292a0 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68  ively..** In oth
292b0 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e  er words, the in
292c0 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22  itial ":" or "$"
292d0 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a   or "@" or "?".*
292e0 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73  * is included as
292f0 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d   part of the nam
29300 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74  e.)^.** ^Paramet
29310 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
29320 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f  "?" without a fo
29330 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20  llowing integer 
29340 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20  have no name.** 
29350 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64  and are referred
29360 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73   to as "nameless
29370 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20  " or "anonymous 
29380 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a  parameters"..**.
29390 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f  ** ^The first ho
293a0 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  st parameter has
293b0 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20   an index of 1, 
293c0 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  not 0..**.** ^If
293d0 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20   the value N is 
293e0 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20  out of range or 
293f0 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61  if the N-th para
29400 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65  meter is.** name
29410 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20  less, then NULL 
29420 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54  is returned.  ^T
29430 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
29440 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20  ng is.** always 
29450 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  in UTF-8 encodin
29460 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61  g even if the na
29470 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61  med parameter wa
29480 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20  s.** originally 
29490 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46  specified as UTF
294a0 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  -16 in [sqlite3_
294b0 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a  prepare16()] or.
294c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
294d0 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
294e0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
294f0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
29500 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
29510 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
29520 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
29530 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
29540 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
29550 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
29560 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
29570 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
29580 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65  eter_name(sqlite
29590 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a  3_stmt*, int);..
295a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
295b0 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d  Index Of A Param
295c0 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65  eter With A Give
295d0 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65  n Name.**.** ^Re
295e0 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f  turn the index o
295f0 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74  f an SQL paramet
29600 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d  er given its nam
29610 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65  e.  ^The.** inde
29620 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  x value returned
29630 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72   is suitable for
29640 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f   use as the seco
29650 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  nd.** parameter 
29660 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
29670 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
29680 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a  nd()].  ^A zero.
29690 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
296a0 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61  f no matching pa
296b0 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64  rameter is found
296c0 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  .  ^The paramete
296d0 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62  r.** name must b
296e0 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38  e given in UTF-8
296f0 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69   even if the ori
29700 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a  ginal statement.
29710 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20  ** was prepared 
29720 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74  from UTF-16 text
29730 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
29740 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
29750 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
29760 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
29770 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
29780 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
29790 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
297a0 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
297b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
297c0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
297d0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
297e0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
297f0 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73  _index(sqlite3_s
29800 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  tmt*, const char
29810 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a   *zName);../*.**
29820 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
29830 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e   All Bindings On
29840 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
29850 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  ement.**.** ^Con
29860 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74  trary to the int
29870 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20  uition of many, 
29880 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
29890 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74  ] does not reset
298a0 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
298b0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e  _bind_blob | bin
298c0 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65  dings] on a [pre
298d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
298e0 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72  ..** ^Use this r
298f0 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20  outine to reset 
29900 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  all host paramet
29910 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a  ers to NULL..*/.
29920 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61  int sqlite3_clea
29930 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
29940 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
29950 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
29960 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e  er Of Columns In
29970 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
29980 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
29990 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
299a0 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
299b0 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  set returned by 
299c0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
299d0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68   statement]. ^Th
299e0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
299f0 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73  ns 0 if pStmt is
29a00 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65   an SQL.** state
29a10 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e  ment that does n
29a20 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28  ot return data (
29a30 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b  for example an [
29a40 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20  UPDATE])..**.** 
29a50 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
29a60 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d  e3_data_count()]
29a70 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
29a80 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c  column_count(sql
29a90 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
29aa0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
29ab0 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73  EF: Column Names
29ac0 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
29ad0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
29ae0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
29af0 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20  e name assigned 
29b00 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  to a particular 
29b10 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65  column.** in the
29b20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
29b30 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
29b40 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ent.  ^The sqlit
29b50 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
29b60 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
29b70 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
29b80 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
29b90 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
29ba0 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  g.** and sqlite3
29bb0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
29bc0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
29bd0 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
29be0 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
29bf0 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
29c00 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
29c10 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  is the [prepared
29c20 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74   statement].** t
29c30 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
29c40 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
29c50 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f  ement. ^The seco
29c60 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
29c70 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75  the.** column nu
29c80 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74  mber.  ^The left
29c90 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e  most column is n
29ca0 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  umber 0..**.** ^
29cb0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
29cc0 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76  ing pointer is v
29cd0 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65  alid until eithe
29ce0 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
29cf0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73  statement].** is
29d00 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73   destroyed by [s
29d10 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
29d20 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
29d30 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74  statement is aut
29d40 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65  omatically.** re
29d50 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20  prepared by the 
29d60 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73  first call to [s
29d70 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
29d80 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
29d90 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  run.** or until 
29da0 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f  the next call to
29db0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
29dc0 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c  mn_name() or sql
29dd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
29de0 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65  16() on the same
29df0 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
29e00 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
29e10 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67  c() fails during
29e20 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20   the processing 
29e30 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e  of either routin
29e40 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c  e.** (for exampl
29e50 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65  e during a conve
29e60 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38  rsion from UTF-8
29e70 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e   to UTF-16) then
29e80 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
29e90 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
29ea0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
29eb0 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  of a result colu
29ec0 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  mn is the value 
29ed0 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75  of the "AS" clau
29ee0 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63  se for.** that c
29ef0 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20  olumn, if there 
29f00 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e  is an AS clause.
29f10 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f    If there is no
29f20 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68   AS clause.** th
29f30 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  en the name of t
29f40 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73  he column is uns
29f50 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79  pecified and may
29f60 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20   change from.** 
29f70 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  one release of S
29f80 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78  QLite to the nex
29f90 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  t..*/.const char
29fa0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
29fb0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
29fc0 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e  mt*, int N);.con
29fd0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
29fe0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73  _column_name16(s
29ff0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2a000 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t N);../*.** CAP
2a010 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66  I3REF: Source Of
2a020 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79   Data In A Query
2a030 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54   Result.**.** ^T
2a040 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72  hese routines pr
2a050 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f  ovide a means to
2a060 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
2a070 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
2a080 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c  and.** table col
2a090 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20  umn that is the 
2a0a0 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74  origin of a part
2a0b0 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f  icular result co
2a0c0 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45  lumn in.** [SELE
2a0d0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  CT] statement..*
2a0e0 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  * ^The name of t
2a0f0 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74  he database or t
2a100 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63  able or column c
2a110 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  an be returned a
2a120 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54  s.** either a UT
2a130 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74  F-8 or UTF-16 st
2a140 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74  ring.  ^The _dat
2a150 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20  abase_ routines 
2a160 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61  return.** the da
2a170 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65  tabase name, the
2a180 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65   _table_ routine
2a190 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62  s return the tab
2a1a0 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20  le name, and.** 
2a1b0 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74  the origin_ rout
2a1c0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
2a1d0 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20  column name..** 
2a1e0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2a1f0 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e  ring is valid un
2a200 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65  til the [prepare
2a210 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20  d statement] is 
2a220 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69  destroyed.** usi
2a230 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
2a240 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
2a250 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2a260 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  s automatically.
2a270 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79  ** reprepared by
2a280 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
2a290 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2a2a0 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63  ()] for a partic
2a2b0 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75  ular run.** or u
2a2c0 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e  ntil the same in
2a2d0 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71  formation is req
2a2e0 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20  uested.** again 
2a2f0 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65  in a different e
2a300 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  ncoding..**.** ^
2a310 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e  The names return
2a320 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69  ed are the origi
2a330 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e  nal un-aliased n
2a340 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64  ames of the.** d
2a350 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
2a360 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
2a370 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
2a380 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69  ument to these i
2a390 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b  nterfaces is a [
2a3a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a3b0 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66  nt]..** ^These f
2a3c0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
2a3d0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
2a3e0 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74  t the Nth result
2a3f0 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
2a400 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65   by.** the state
2a410 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73  ment, where N is
2a420 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
2a430 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
2a440 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74  * ^The left-most
2a450 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d   column is colum
2a460 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f  n 0 for these ro
2a470 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  utines..**.** ^I
2a480 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
2a490 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
2a4a0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e   statement is an
2a4b0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a   expression or.*
2a4c0 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69  * subquery and i
2a4d0 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76  s not a column v
2a4e0 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f  alue, then all o
2a4f0 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
2a500 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c  s return.** NULL
2a510 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
2a520 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74  e might also ret
2a530 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65  urn NULL if a me
2a540 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2a550 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e  error.** occurs.
2a560 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68    ^Otherwise, th
2a570 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  ey return the na
2a580 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68  me of the attach
2a590 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ed database, tab
2a5a0 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e  le,.** or column
2a5b0 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75   that query resu
2a5c0 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78  lt column was ex
2a5d0 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a  tracted from..**
2a5e0 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c  .** ^As with all
2a5f0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50   other SQLite AP
2a600 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20  Is, those whose 
2a610 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22  names end with "
2a620 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54  16" return.** UT
2a630 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72  F-16 encoded str
2a640 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68  ings and the oth
2a650 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  er functions ret
2a660 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a  urn UTF-8..**.**
2a670 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65   ^These APIs are
2a680 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
2a690 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77  if the library w
2a6a0 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
2a6b0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
2a6c0 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
2a6d0 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f  TADATA] C-prepro
2a6e0 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a  cessor symbol..*
2a6f0 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
2a700 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
2a710 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
2a720 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
2a730 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a  gainst the same.
2a740 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
2a750 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e  ement and column
2a760 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
2a770 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
2a780 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69  ts are.** undefi
2a790 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  ned..**.** If tw
2a7a0 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
2a7b0 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
2a7c0 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  re.** [sqlite3_c
2a7d0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
2a7e0 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74  ame | column met
2a7f0 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73  adata interfaces
2a800 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ].** for the sam
2a810 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2a820 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c  ement] and resul
2a830 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74  t column.** at t
2a840 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
2a850 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
2a860 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
2a870 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2a880 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
2a890 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ase_name(sqlite3
2a8a0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
2a8b0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2a8c0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
2a8d0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
2a8e0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
2a8f0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2a900 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
2a910 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2a920 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
2a930 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2a940 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71  _table_name16(sq
2a950 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2a960 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
2a970 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
2a980 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  gin_name(sqlite3
2a990 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
2a9a0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2a9b0 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
2a9c0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2a9d0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
2a9e0 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
2a9f0 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20  red Datatype Of 
2aa00 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
2aa10 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74  *.** ^(The first
2aa20 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
2aa30 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2aa40 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ent]..** If this
2aa50 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
2aa60 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2aa70 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63  nt and the Nth c
2aa80 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  olumn of the.** 
2aa90 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20  returned result 
2aaa0 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c  set of that [SEL
2aab0 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20  ECT] is a table 
2aac0 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a  column (not an.*
2aad0 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
2aae0 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74  subquery) then t
2aaf0 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
2ab00 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
2ab10 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72   column is retur
2ab20 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20  ned.)^  ^If the 
2ab30 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
2ab40 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20  e result set is 
2ab50 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
2ab60 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68   or subquery, th
2ab70 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
2ab80 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
2ab90 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
2aba0 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73  string is always
2abb0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a   UTF-8 encoded..
2abc0 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d  **.** ^(For exam
2abd0 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64  ple, given the d
2abe0 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a  atabase schema:.
2abf0 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42  **.** CREATE TAB
2ac00 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54  LE t1(c1 VARIANT
2ac10 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65  );.**.** and the
2ac20 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65   following state
2ac30 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
2ac40 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43  led:.**.** SELEC
2ac50 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f  T c1 + 1, c1 FRO
2ac60 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73  M t1;.**.** this
2ac70 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72   routine would r
2ac80 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67  eturn the string
2ac90 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74   "VARIANT" for t
2aca0 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74  he second result
2acb0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31  .** column (i==1
2acc0 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f  ), and a NULL po
2acd0 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69  inter for the fi
2ace0 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  rst result colum
2acf0 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a  n (i==0).)^.**.*
2ad00 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64  * ^SQLite uses d
2ad10 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20  ynamic run-time 
2ad20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73  typing.  ^So jus
2ad30 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75  t because a colu
2ad40 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65  mn.** is declare
2ad50 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70  d to contain a p
2ad60 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64  articular type d
2ad70 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61  oes not mean tha
2ad80 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74  t the.** data st
2ad90 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c  ored in that col
2ada0 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65  umn is of the de
2adb0 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51  clared type.  SQ
2adc0 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e  Lite is.** stron
2add0 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74  gly typed, but t
2ade0 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e  he typing is dyn
2adf0 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e  amic not static.
2ae00 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73    ^Type.** is as
2ae10 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e  sociated with in
2ae20 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c  dividual values,
2ae30 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f   not with the co
2ae40 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64  ntainers.** used
2ae50 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76   to hold those v
2ae60 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  alues..*/.const 
2ae70 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2ae80 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71  lumn_decltype(sq
2ae90 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2aea0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2aeb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
2aec0 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f  ltype16(sqlite3_
2aed0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
2aee0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61  ** CAPI3REF: Eva
2aef0 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61  luate An SQL Sta
2af00 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74  tement.**.** Aft
2af10 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  er a [prepared s
2af20 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65  tatement] has be
2af30 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  en prepared usin
2af40 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c  g either.** [sql
2af50 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2af60 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
2af70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
2af80 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67  r one of the leg
2af90 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
2afa0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
2afb0 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  re()] or [sqlite
2afc0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20  3_prepare16()], 
2afd0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  this function.**
2afe0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
2aff0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
2b000 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68  s to evaluate th
2b010 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  e statement..**.
2b020 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f  ** The details o
2b030 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  f the behavior o
2b040 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  f the sqlite3_st
2b050 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64  ep() interface d
2b060 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74  epend.** on whet
2b070 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e  her the statemen
2b080 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75  t was prepared u
2b090 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22  sing the newer "
2b0a0 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  v2" interface.**
2b0b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2b0c0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
2b0d0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2b0e0 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65  2()] or the olde
2b0f0 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  r legacy.** inte
2b100 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70  rface [sqlite3_p
2b110 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
2b120 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2b130 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66  ()].  The use of
2b140 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22   the.** new "v2"
2b150 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
2b160 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65  commended for ne
2b170 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62  w applications b
2b180 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ut the legacy.**
2b190 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
2b1a0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73  continue to be s
2b1b0 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  upported..**.** 
2b1c0 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69  ^In the legacy i
2b1d0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65  nterface, the re
2b1e0 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20  turn value will 
2b1f0 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  be either [SQLIT
2b200 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_BUSY],.** [SQL
2b210 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49  ITE_DONE], [SQLI
2b220 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45  TE_ROW], [SQLITE
2b230 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c  _ERROR], or [SQL
2b240 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20  ITE_MISUSE]..** 
2b250 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69  ^With the "v2" i
2b260 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66  nterface, any of
2b270 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75   the other [resu
2b280 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20  lt codes] or.** 
2b290 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
2b2a0 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65   codes] might be
2b2b0 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c   returned as wel
2b2c0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  l..**.** ^[SQLIT
2b2d0 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68  E_BUSY] means th
2b2e0 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
2b2f0 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c  engine was unabl
2b300 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65  e to acquire the
2b310 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63  .** database loc
2b320 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64  ks it needs to d
2b330 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20  o its job.  ^If 
2b340 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2b350 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f   a [COMMIT].** o
2b360 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65  r occurs outside
2b370 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   of an explicit 
2b380 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
2b390 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20  n you can retry 
2b3a0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
2b3b0 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  .  If the statem
2b3c0 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f  ent is not a [CO
2b3d0 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73  MMIT] and occurs
2b3e0 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78   within an.** ex
2b3f0 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
2b400 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75  on then you shou
2b410 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20  ld rollback the 
2b420 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f  transaction befo
2b430 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67  re.** continuing
2b440 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
2b450 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61  _DONE] means tha
2b460 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
2b470 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
2b480 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73  cuting.** succes
2b490 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33  sfully.  sqlite3
2b4a0 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
2b4b0 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
2b4c0 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75  in on this virtu
2b4d0 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69  al.** machine wi
2b4e0 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c  thout first call
2b4f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
2b500 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  et()] to reset t
2b510 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  he virtual.** ma
2b520 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74  chine back to it
2b530 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e  s initial state.
2b540 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53  .**.** ^If the S
2b550 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69  QL statement bei
2b560 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75  ng executed retu
2b570 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68  rns any data, th
2b580 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a  en [SQLITE_ROW].
2b590 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65  ** is returned e
2b5a0 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72  ach time a new r
2b5b0 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65  ow of data is re
2b5c0 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69  ady for processi
2b5d0 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c  ng by the.** cal
2b5e0 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20  ler. The values 
2b5f0 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20  may be accessed 
2b600 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d  using the [colum
2b610 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
2b620 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ns]..** sqlite3_
2b630 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64  step() is called
2b640 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65   again to retrie
2b650 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20  ve the next row 
2b660 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e  of data..**.** ^
2b670 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d  [SQLITE_ERROR] m
2b680 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d  eans that a run-
2b690 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68  time error (such
2b6a0 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   as a constraint
2b6b0 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68  .** violation) h
2b6c0 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71  as occurred.  sq
2b6d0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
2b6e0 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
2b6f0 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68  d again on.** th
2b700 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72  e VM. More infor
2b710 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f  mation may be fo
2b720 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  und by calling [
2b730 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
2b740 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20  ]..** ^With the 
2b750 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
2b760 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69  , a more specifi
2b770 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f  c error code (fo
2b780 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53  r example,.** [S
2b790 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
2b7a0 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  , [SQLITE_SCHEMA
2b7b0 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55  ], [SQLITE_CORRU
2b7c0 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74  PT], and so fort
2b7d0 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74  h).** can be obt
2b7e0 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67  ained by calling
2b7f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2b800 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72  )] on the.** [pr
2b810 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b820 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22  ].  ^In the "v2"
2b830 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74   interface,.** t
2b840 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
2b850 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72   error code is r
2b860 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
2b870 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
2b880 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ()..**.** [SQLIT
2b890 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20  E_MISUSE] means 
2b8a0 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f  that the this ro
2b8b0 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64  utine was called
2b8c0 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79   inappropriately
2b8d0 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20  ..** Perhaps it 
2b8e0 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20  was called on a 
2b8f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b900 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a  ent] that has.**
2b910 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73   already been [s
2b920 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
2b930 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20  | finalized] or 
2b940 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a  on one that had.
2b950 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ** previously re
2b960 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45  turned [SQLITE_E
2b970 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45  RROR] or [SQLITE
2b980 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63  _DONE].  Or it c
2b990 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63  ould.** be the c
2b9a0 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d  ase that the sam
2b9b0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2b9c0 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75  ction is being u
2b9d0 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a  sed by two or.**
2b9e0 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74   more threads at
2b9f0 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74   the same moment
2ba00 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20   in time..**.** 
2ba10 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73  For all versions
2ba20 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f   of SQLite up to
2ba30 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33   and including 3
2ba40 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20  .6.23.1, a call 
2ba50 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  to.** [sqlite3_r
2ba60 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75  eset()] was requ
2ba70 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74  ired after sqlit
2ba80 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e  e3_step() return
2ba90 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f  ed anything.** o
2baa0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
2bab0 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e  E_ROW] before an
2bac0 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  y subsequent inv
2bad0 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71  ocation of.** sq
2bae0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46  lite3_step().  F
2baf0 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20  ailure to reset 
2bb00 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
2bb10 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a  tement using .**
2bb20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2bb30 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20  )] would result 
2bb40 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  in an [SQLITE_MI
2bb50 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f  SUSE] return fro
2bb60 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  m.** sqlite3_ste
2bb70 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20  p().  But after 
2bb80 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31  version 3.6.23.1
2bb90 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  , sqlite3_step()
2bba0 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e   began.** callin
2bbb0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2bbc0 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ()] automaticall
2bbd0 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d  y in this circum
2bbe0 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a  stance rather.**
2bbf0 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20   than returning 
2bc00 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2bc10 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f    This is not co
2bc20 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61  nsidered a compa
2bc30 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61  tibility.** brea
2bc40 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61 70  k because any ap
2bc50 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65  plication that e
2bc60 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e 20  ver receives an 
2bc70 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72  SQLITE_MISUSE er
2bc80 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e  ror.** is broken
2bc90 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   by definition. 
2bca0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49   The [SQLITE_OMI
2bcb0 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d  T_AUTORESET] com
2bcc0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
2bcd0 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20  .** can be used 
2bce0 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c  to restore the l
2bcf0 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a  egacy behavior..
2bd00 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49  **.** <b>Goofy I
2bd10 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c  nterface Alert:<
2bd20 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63  /b> In the legac
2bd30 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
2bd40 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a   sqlite3_step().
2bd50 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65  ** API always re
2bd60 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20  turns a generic 
2bd70 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c  error code, [SQL
2bd80 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c  ITE_ERROR], foll
2bd90 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72  owing any.** err
2bda0 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  or other than [S
2bdb0 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20  QLITE_BUSY] and 
2bdc0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2bdd0 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a    You must call.
2bde0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
2bdf0 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
2be00 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20  _finalize()] in 
2be10 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e  order to find on
2be20 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63  e of the.** spec
2be30 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
2be40 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64  s] that better d
2be50 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
2be60 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20  or..** We admit 
2be70 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67  that this is a g
2be80 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68  oofy design.  Th
2be90 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65  e problem has be
2bea0 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68  en fixed.** with
2beb0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
2bec0 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65  ace.  If you pre
2bed0 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72  pare all of your
2bee0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
2bef0 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ** using either 
2bf00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2bf10 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
2bf20 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2bf30 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  )] instead.** of
2bf40 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c   the legacy [sql
2bf50 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
2bf60 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
2bf70 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66  pare16()] interf
2bf80 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  aces,.** then th
2bf90 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
2bfa0 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72  [error codes] ar
2bfb0 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  e returned direc
2bfc0 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  tly.** by sqlite
2bfd0 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75  3_step().  The u
2bfe0 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69  se of the "v2" i
2bff0 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
2c000 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20  mmended..*/.int 
2c010 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c  sqlite3_step(sql
2c020 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
2c030 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
2c040 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2c050 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a  in a result set.
2c060 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2c070 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2c080 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2c090 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2c0a0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a   columns in the.
2c0b0 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  ** current row o
2c0c0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2c0d0 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
2c0e0 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
2c0f0 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74  If prepared stat
2c100 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74  ement P does not
2c110 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65   have results re
2c120 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ady to return.**
2c130 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74   (via calls to t
2c140 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
2c150 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  mn_int | sqlite3
2c160 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a  _column_*()] of.
2c170 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74  ** interfaces) t
2c180 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61  hen sqlite3_data
2c190 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e  _count(P) return
2c1a0 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s 0..** ^The sql
2c1b0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2c1c0 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20  P) routine also 
2c1d0 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69  returns 0 if P i
2c1e0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2c1f0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2c200 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
2c210 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2c220 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  0 if the previou
2c230 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  s call to.** [sq
2c240 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
2c250 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2c260 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c  DONE].  ^The sql
2c270 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2c280 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72  P).** will retur
2c290 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72  n non-zero if pr
2c2a0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b  evious call to [
2c2b0 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29  sqlite3_step](P)
2c2c0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51   returned.** [SQ
2c2d0 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70  LITE_ROW], excep
2c2e0 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66  t in the case of
2c2f0 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63   the [PRAGMA inc
2c300 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d  remental_vacuum]
2c310 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77  .** where it alw
2c320 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ays returns zero
2c330 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70   since each step
2c340 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73   of that multi-s
2c350 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65  tep.** pragma re
2c360 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20  turns 0 columns 
2c370 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53  of data..**.** S
2c380 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2c390 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
2c3a0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
2c3b0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69  _data_count(sqli
2c3c0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2c3d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2c3e0 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44  F: Fundamental D
2c3f0 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57  atatypes.** KEYW
2c400 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58  ORDS: SQLITE_TEX
2c410 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20  T.**.** ^(Every 
2c420 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20  value in SQLite 
2c430 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20  has one of five 
2c440 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61  fundamental data
2c450 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  types:.**.** <ul
2c460 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  >.** <li> 64-bit
2c470 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
2c480 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49  ** <li> 64-bit I
2c490 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  EEE floating poi
2c4a0 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69  nt number.** <li
2c4b0 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e  > string.** <li>
2c4c0 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55   BLOB.** <li> NU
2c4d0 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  LL.** </ul>)^.**
2c4e0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
2c4f0 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f  nts are codes fo
2c500 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20  r each of those 
2c510 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  types..**.** Not
2c520 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54  e that the SQLIT
2c530 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20  E_TEXT constant 
2c540 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e  was also used in
2c550 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2c560 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c  2.** for a compl
2c570 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20  etely different 
2c580 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61  meaning.  Softwa
2c590 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  re that links ag
2c5a0 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51  ainst both.** SQ
2c5b0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61  Lite version 2 a
2c5c0 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
2c5d0 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53  n 3 should use S
2c5e0 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74  QLITE3_TEXT, not
2c5f0 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e  .** SQLITE_TEXT.
2c600 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
2c610 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64  TE_INTEGER  1.#d
2c620 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f  efine SQLITE_FLO
2c630 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  AT    2.#define 
2c640 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20  SQLITE_BLOB     
2c650 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
2c660 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64  _NULL     5.#ifd
2c670 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
2c680 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45   undef SQLITE_TE
2c690 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  XT.#else.# defin
2c6a0 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20  e SQLITE_TEXT   
2c6b0 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69    3.#endif.#defi
2c6c0 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  ne SQLITE3_TEXT 
2c6d0 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      3../*.** CAP
2c6e0 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61  I3REF: Result Va
2c6f0 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72  lues From A Quer
2c700 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  y.** KEYWORDS: {
2c710 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
2c720 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54  nctions}.**.** T
2c730 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hese routines fo
2c740 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73  rm the "result s
2c750 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  et" interface..*
2c760 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
2c770 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ines return info
2c780 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20  rmation about a 
2c790 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66  single column of
2c7a0 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
2c7b0 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20  result row of a 
2c7c0 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72  query.  ^In ever
2c7d0 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74  y case the first
2c7e0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
2c7f0 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
2c800 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2c810 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65  ment] that is be
2c820 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74  ing evaluated (t
2c830 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
2c840 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72  *].** that was r
2c850 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
2c860 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2c870 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74  ()] or one of it
2c880 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61  s variants).** a
2c890 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  nd the second ar
2c8a0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
2c8b0 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
2c8c0 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f  n for which info
2c8d0 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  rmation.** shoul
2c8e0 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e  d be returned. ^
2c8f0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
2c900 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
2c910 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e  t set has the in
2c920 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e  dex 0..** ^The n
2c930 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2c940 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63   in the result c
2c950 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
2c960 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
2c970 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
2c980 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  )]..**.** If the
2c990 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64   SQL statement d
2c9a0 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c  oes not currentl
2c9b0 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c  y point to a val
2c9c0 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68  id row, or if th
2c9d0 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65  e.** column inde
2c9e0 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
2c9f0 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  e, the result is
2ca00 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
2ca10 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61  hese routines ma
2ca20 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  y only be called
2ca30 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72   when the most r
2ca40 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  ecent call to.**
2ca50 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2ca60 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b  ] has returned [
2ca70 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20  SQLITE_ROW] and 
2ca80 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69  neither.** [sqli
2ca90 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72  te3_reset()] nor
2caa0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2cab0 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20  ze()] have been 
2cac0 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e  called subsequen
2cad0 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f  tly..** If any o
2cae0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2caf0 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65   are called afte
2cb00 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
2cb10 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
2cb20 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
2cb30 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  r after [sqlite3
2cb40 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
2cb50 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69  urned.** somethi
2cb60 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ng other than [S
2cb70 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20  QLITE_ROW], the 
2cb80 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2cb90 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71  fined..** If [sq
2cba0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
2cbb0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2cbc0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
2cbd0 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72  inalize()].** ar
2cbe0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20  e called from a 
2cbf0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
2cc00 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68   while any of th
2cc10 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
2cc20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65  are pending, the
2cc30 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
2cc40 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
2cc50 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2cc60 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f  column_type() ro
2cc70 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
2cc80 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e.** [SQLITE_INT
2cc90 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20  EGER | datatype 
2cca0 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e  code] for the in
2ccb0 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a  itial data type.
2ccc0 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ** of the result
2ccd0 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72   column.  ^The r
2cce0 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73  eturned value is
2ccf0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
2cd00 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51  INTEGER],.** [SQ
2cd10 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
2cd20 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c  LITE_TEXT], [SQL
2cd30 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53  ITE_BLOB], or [S
2cd40 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68  QLITE_NULL].  Th
2cd50 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
2cd60 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2cd70 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
2cd80 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20  only meaningful 
2cd90 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f  if no type.** co
2cda0 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f  nversions have o
2cdb0 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72  ccurred as descr
2cdc0 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74  ibed below.  Aft
2cdd0 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  er a type conver
2cde0 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c  sion,.** the val
2cdf0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
2ce00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2ce10 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  pe() is undefine
2ce20 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65  d.  Future.** ve
2ce30 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
2ce40 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20   may change the 
2ce50 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
2ce60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2ce70 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  ).** following a
2ce80 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
2ce90 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2cea0 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
2ceb0 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67   or UTF-8 string
2cec0 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
2ced0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2cee0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
2cef0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2cf00 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
2cf10 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
2cf20 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2cf30 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74  t is a UTF-16 st
2cf40 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
2cf50 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2cf60 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
2cf70 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
2cf80 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  8 and then retur
2cf90 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2cfa0 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
2cfb0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
2cfc0 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
2cfd0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2cfe0 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a  _bytes() uses.**
2cff0 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
2d000 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
2d010 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
2d020 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e   UTF-8 string an
2d030 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
2d040 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2d050 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
2d060 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2d070 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
2d080 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d090 62 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20  bytes() returns 
2d0a0 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  zero..**.** ^If 
2d0b0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2d0c0 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73  BLOB or UTF-16 s
2d0d0 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
2d0e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2d0f0 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  tes16().** routi
2d100 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
2d110 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2d120 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
2d130 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2d140 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
2d150 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  F-8 string, then
2d160 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d170 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72  bytes16() conver
2d180 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
2d190 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74   to UTF-16 and t
2d1a0 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
2d1b0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
2d1c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2d1d0 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
2d1e0 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
2d1f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2d200 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  6() uses.** [sql
2d210 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
2d220 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
2d230 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
2d240 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  16 string and re
2d250 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
2d260 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2d270 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
2d280 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2d290 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c  s NULL, then sql
2d2a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2d2b0 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65  s16() returns ze
2d2c0 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76  ro..**.** ^The v
2d2d0 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
2d2e0 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
2d2f0 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a  n_bytes()] and .
2d300 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2d310 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f  mn_bytes16()] do
2d320 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65   not include the
2d330 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2d340 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20  s at the end.** 
2d350 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20  of the string.  
2d360 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68  ^For clarity: th
2d370 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
2d380 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
2d390 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d  _column_bytes()]
2d3a0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f   and [sqlite3_co
2d3b0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
2d3c0 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  are the number o
2d3d0 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68  f.** bytes in th
2d3e0 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68  e string, not th
2d3f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
2d400 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53  acters..**.** ^S
2d410 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
2d420 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2d430 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c  n_text() and sql
2d440 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2d450 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d  16(),.** even em
2d460 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65  pty strings, are
2d470 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
2d480 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72  minated.  ^The r
2d490 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66  eturn.** value f
2d4a0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  rom sqlite3_colu
2d4b0 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20  mn_blob() for a 
2d4c0 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
2d4d0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2d4e0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f  er..**.** ^The o
2d4f0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
2d500 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
2d510 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e  n_value()] is an
2d520 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
2d530 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2d540 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72  object.  An unpr
2d550 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2d560 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20  value object.** 
2d570 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
2d580 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62   with [sqlite3_b
2d590 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ind_value()] and
2d5a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2d5b0 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66  _value()]..** If
2d5c0 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65   the [unprotecte
2d5d0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2d5e0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
2d5f0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
2d600 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
2d610 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f  is used in any o
2d620 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64  ther way, includ
2d630 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  ing calls.** to 
2d640 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
2d650 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
2d660 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
2d670 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
2d680 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
2d690 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e  e_bytes()], then
2d6a0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
2d6b0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2d6c0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2d6d0 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76   attempt to conv
2d6e0 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68  ert the value wh
2d6f0 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e  ere appropriate.
2d700 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c    ^For.** exampl
2d710 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e  e, if the intern
2d720 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
2d730 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61  n is FLOAT and a
2d740 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20   text result.** 
2d750 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73  is requested, [s
2d760 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
2d770 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  )] is used inter
2d780 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d  nally to perform
2d790 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69   the.** conversi
2d7a0 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  on automatically
2d7b0 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69  .  ^(The followi
2d7c0 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73  ng table details
2d7d0 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73   the conversions
2d7e0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70  .** that are app
2d7f0 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lied:.**.** <blo
2d800 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62  ckquote>.** <tab
2d810 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a  le border="1">.*
2d820 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72  * <tr><th> Inter
2d830 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  nal<br>Type <th>
2d840 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79   Requested<br>Ty
2d850 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73  pe <th>  Convers
2d860 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
2d870 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2d880 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
2d890 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c  Result is 0.** <
2d8a0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
2d8b0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
2d8c0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
2d8d0 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  .0.** <tr><td>  
2d8e0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54  NULL    <td>   T
2d8f0 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  EXT    <td> Resu
2d900 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74  lt is NULL point
2d910 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
2d920 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42  NULL    <td>   B
2d930 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75  LOB    <td> Resu
2d940 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74  lt is NULL point
2d950 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
2d960 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c  NTEGER  <td>  FL
2d970 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
2d980 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72  ert from integer
2d990 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72   to float.** <tr
2d9a0 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
2d9b0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
2d9c0 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
2d9d0 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65  ng of the intege
2d9e0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
2d9f0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c  TEGER  <td>   BL
2da00 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
2da10 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54  as INTEGER->TEXT
2da20 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
2da30 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OAT   <td> INTEG
2da40 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  ER   <td> Conver
2da50 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20  t from float to 
2da60 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c  integer.** <tr><
2da70 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
2da80 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2da90 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
2daa0 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a   of the float.**
2dab0 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
2dac0 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
2dad0 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46    <td> Same as F
2dae0 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  LOAT->TEXT.** <t
2daf0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
2db00 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2db10 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a  td> Use atoi().*
2db20 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
2db30 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
2db40 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66     <td> Use atof
2db50 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
2db60 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42  TEXT    <td>   B
2db70 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63  LOB    <td> No c
2db80 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64  hange.** <tr><td
2db90 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
2dba0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43  INTEGER   <td> C
2dbb0 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
2dbc0 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a  hen use atoi().*
2dbd0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
2dbe0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
2dbf0 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
2dc00 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65  to TEXT then use
2dc10 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atof().** <tr><
2dc20 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
2dc30 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2dc40 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d   Add a zero term
2dc50 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64  inator if needed
2dc60 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20  .** </table>.** 
2dc70 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
2dc80 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
2dc90 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65  above makes refe
2dca0 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72  rence to standar
2dcb0 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63  d C library func
2dcc0 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20  tions atoi().** 
2dcd0 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c  and atof().  SQL
2dce0 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61  ite does not rea
2dcf0 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75  lly use these fu
2dd00 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73  nctions.  It has
2dd10 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69   its.** own equi
2dd20 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20  valent internal 
2dd30 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61  routines.  The a
2dd40 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29  toi() and atof()
2dd50 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73   names are.** us
2dd60 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20  ed in the table 
2dd70 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20  for brevity and 
2dd80 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65  because they are
2dd90 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73   familiar to mos
2dda0 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65  t.** C programme
2ddb0 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  rs..**.** Note t
2ddc0 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f  hat when type co
2ddd0 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c  nversions occur,
2dde0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
2ddf0 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63  ed by prior.** c
2de00 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2de10 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73  column_blob(), s
2de20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2de30 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20  xt(), and/or.** 
2de40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2de50 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69  ext16() may be i
2de60 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54  nvalidated..** T
2de70 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
2de80 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61  and pointer inva
2de90 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lidations might 
2dea0 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20  occur.** in the 
2deb0 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a  following cases:
2dec0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
2ded0 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
2dee0 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f  content is a BLO
2def0 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  B and sqlite3_co
2df00 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a  lumn_text() or.*
2df10 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
2df20 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
2df30 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72  s called.  A zer
2df40 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67  o-terminator mig
2df50 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20  ht.**      need 
2df60 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74  to be added to t
2df70 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a  he string.</li>.
2df80 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
2df90 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
2dfa0 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71  TF-8 text and sq
2dfb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2dfc0 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20  es16() or.**    
2dfd0 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
2dfe0 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
2dff0 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
2e000 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
2e010 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
2e020 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  TF-16.</li>.** <
2e030 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
2e040 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31  content is UTF-1
2e050 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  6 text and sqlit
2e060 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2e070 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
2e080 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2e090 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
2e0a0 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
2e0b0 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
2e0c0 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f       to UTF-8.</
2e0d0 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
2e0e0 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20  ** ^Conversions 
2e0f0 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65  between UTF-16be
2e100 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72   and UTF-16le ar
2e110 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e  e always done in
2e120 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a   place and do.**
2e130 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20   not invalidate 
2e140 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c  a prior pointer,
2e150 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73   though of cours
2e160 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  e the content of
2e170 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74   the buffer.** t
2e180 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f  hat the prior po
2e190 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73  inter references
2e1a0 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20   will have been 
2e1b0 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72  modified.  Other
2e1c0 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e   kinds.** of con
2e1d0 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65  version are done
2e1e0 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69   in place when i
2e1f0 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62  t is possible, b
2e200 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65  ut sometimes the
2e210 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73  y.** are not pos
2e220 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f  sible and in tho
2e230 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70  se cases prior p
2e240 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61  ointers are inva
2e250 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  lidated..**.** T
2e260 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61  he safest and ea
2e270 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65  siest to remembe
2e280 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69  r policy is to i
2e290 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74  nvoke these rout
2e2a0 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f  ines.** in one o
2e2b0 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
2e2c0 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ways:.**.** <ul>
2e2d0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
2e2e0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66  _column_text() f
2e2f0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
2e300 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2e310 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
2e320 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2e330 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  ob() followed by
2e340 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e350 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
2e360 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
2e370 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c  umn_text16() fol
2e380 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
2e390 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2e3a0 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  )</li>.** </ul>.
2e3b0 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  **.** In other w
2e3c0 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64  ords, you should
2e3d0 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f   call sqlite3_co
2e3e0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20  lumn_text(),.** 
2e3f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2e400 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  lob(), or sqlite
2e410 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2e420 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65  ) first to force
2e430 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69   the result.** i
2e440 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20  nto the desired 
2e450 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76  format, then inv
2e460 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  oke sqlite3_colu
2e470 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
2e480 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e490 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e  bytes16() to fin
2e4a0 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  d the size of th
2e4b0 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f  e result.  Do no
2e4c0 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74  t mix calls.** t
2e4d0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2e4e0 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
2e4f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2e500 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a   with calls to.*
2e510 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
2e520 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20  _bytes16(), and 
2e530 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  do not mix calls
2e540 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
2e550 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77  mn_text16().** w
2e560 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ith calls to sql
2e570 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2e580 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s()..**.** ^The 
2e590 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
2e5a0 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69  d are valid unti
2e5b0 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  l a type convers
2e5c0 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a  ion occurs as.**
2e5d0 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65   described above
2e5e0 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69  , or until [sqli
2e5f0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
2e600 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2e610 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2e620 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63  finalize()] is c
2e630 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d  alled.  ^The mem
2e640 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74  ory space used t
2e650 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a  o hold strings.*
2e660 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66  * and BLOBs is f
2e670 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  reed automatical
2e680 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f  ly.  Do <b>not</
2e690 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e  b> pass the poin
2e6a0 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ters returned.**
2e6b0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
2e6c0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b  olumn_blob()], [
2e6d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2e6e0 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74  ext()], etc. int
2e6f0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  o.** [sqlite3_fr
2e700 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  ee()]..**.** ^(I
2e710 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
2e720 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75  ation error occu
2e730 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76  rs during the ev
2e740 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a  aluation of any.
2e750 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ** of these rout
2e760 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20  ines, a default 
2e770 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65  value is returne
2e780 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  d.  The default 
2e790 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68  value.** is eith
2e7a0 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30  er the integer 0
2e7b0 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70  , the floating p
2e7c0 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c  oint number 0.0,
2e7d0 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   or a NULL.** po
2e7e0 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65  inter.  Subseque
2e7f0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
2e800 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
2e810 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  will return.** [
2e820 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e  SQLITE_NOMEM].)^
2e830 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  .*/.const void *
2e840 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2e850 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
2e860 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
2e870 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2e880 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73  _bytes(sqlite3_s
2e890 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2e8a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2e8b0 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69  umn_bytes16(sqli
2e8c0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2e8d0 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c  Col);.double sql
2e8e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62  ite3_column_doub
2e8f0 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
2e900 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
2e910 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e920 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
2e930 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
2e940 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
2e950 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34  te3_column_int64
2e960 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2e970 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
2e980 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
2e990 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2e9a0 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
2e9b0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
2e9c0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2e9d0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2e9e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2e9f0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
2ea00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2ea10 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2ea20 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69   int iCol);.sqli
2ea30 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74  te3_value *sqlit
2ea40 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
2ea50 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2ea60 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  nt iCol);../*.**
2ea70 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72   CAPI3REF: Destr
2ea80 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74  oy A Prepared St
2ea90 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
2eaa0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2eab0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e  3_finalize() fun
2eac0 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
2ead0 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65  to delete a [pre
2eae0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2eaf0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  ..** ^If the mos
2eb00 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74  t recent evaluat
2eb10 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65  ion of the state
2eb20 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64  ment encountered
2eb30 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72   no errors.** or
2eb40 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
2eb50 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20  t is never been 
2eb60 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20  evaluated, then 
2eb70 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2eb80 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51  () returns.** SQ
2eb90 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68  LITE_OK.  ^If th
2eba0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
2ebb0 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74  aluation of stat
2ebc0 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20  ement S failed, 
2ebd0 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
2ebe0 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75  finalize(S) retu
2ebf0 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69  rns the appropri
2ec00 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
2ec10 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
2ec20 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a   error code]..**
2ec30 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2ec40 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75  _finalize(S) rou
2ec50 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  tine can be call
2ec60 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20  ed at any point 
2ec70 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69  during.** the li
2ec80 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65  fe cycle of [pre
2ec90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2eca0 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74   S:.** before st
2ecb0 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65  atement S is eve
2ecc0 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74  r evaluated, aft
2ecd0 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72  er.** one or mor
2ece0 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  e calls to [sqli
2ecf0 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72  te3_reset()], or
2ed00 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a   after any call.
2ed10 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ** to [sqlite3_s
2ed20 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73  tep()] regardles
2ed30 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
2ed40 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  not the statemen
2ed50 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74  t has.** complet
2ed60 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a  ed execution..**
2ed70 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71  .** ^Invoking sq
2ed80 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2ed90 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   on a NULL point
2eda0 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  er is a harmless
2edb0 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68   no-op..**.** Th
2edc0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
2edd0 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72  st finalize ever
2ede0 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  y [prepared stat
2edf0 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20  ement] in order 
2ee00 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f  to avoid.** reso
2ee10 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20  urce leaks.  It 
2ee20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72  is a grievous er
2ee30 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  ror for the appl
2ee40 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74  ication to try t
2ee50 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61  o use.** a prepa
2ee60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66  red statement af
2ee70 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
2ee80 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20  finalized.  Any 
2ee90 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65  use of a prepare
2eea0 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  d.** statement a
2eeb0 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
2eec0 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72   finalized can r
2eed0 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e  esult in undefin
2eee0 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69  ed and.** undesi
2eef0 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73  rable behavior s
2ef00 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73  uch as segfaults
2ef10 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70   and heap corrup
2ef20 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
2ef30 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71  ite3_finalize(sq
2ef40 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2ef50 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2ef60 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65  REF: Reset A Pre
2ef70 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
2ef80 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65  Object.**.** The
2ef90 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29   sqlite3_reset()
2efa0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
2efb0 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b  led to reset a [
2efc0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2efd0 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61  nt].** object ba
2efe0 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
2eff0 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74  l state, ready t
2f000 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64  o be re-executed
2f010 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74  ..** ^Any SQL st
2f020 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65  atement variable
2f030 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65  s that had value
2f040 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20  s bound to them 
2f050 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71  using.** the [sq
2f060 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
2f070 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  | sqlite3_bind_*
2f080 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74  () API] retain t
2f090 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20  heir values..** 
2f0a0 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65  Use [sqlite3_cle
2f0b0 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74  ar_bindings()] t
2f0c0 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64  o reset the bind
2f0d0 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ings..**.** ^The
2f0e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2f0f0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
2f100 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72  sets the [prepar
2f110 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a  ed statement] S.
2f120 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62  ** back to the b
2f130 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20  eginning of its 
2f140 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  program..**.** ^
2f150 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
2f160 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
2f170 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
2f180 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2f190 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72  d statement] S r
2f1a0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2f1b0 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROW] or [SQLITE_
2f1c0 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20  DONE],.** or if 
2f1d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2f1e0 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f  ] has never befo
2f1f0 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f  re been called o
2f200 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71  n S,.** then [sq
2f210 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
2f220 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
2f230 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  OK]..**.** ^If t
2f240 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
2f250 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2f260 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
2f270 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2f280 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63  atement] S indic
2f290 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74  ated an error, t
2f2a0 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hen.** [sqlite3_
2f2b0 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
2f2c0 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
2f2d0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
2f2e0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
2f2f0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
2f300 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20  erface does not 
2f310 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
2f320 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c  s.** of any [sql
2f330 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62  ite3_bind_blob|b
2f340 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20  indings] on the 
2f350 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2f360 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73  ent] S..*/.int s
2f370 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
2f380 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2f390 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f3a0 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
2f3b0 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
2f3c0 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
2f3d0 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  : {function crea
2f3e0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a  tion routines}.*
2f3f0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
2f400 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2f410 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a   SQL function}.*
2f420 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
2f430 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2f440 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a   SQL functions}.
2f450 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  **.** ^These fun
2f460 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69  ctions (collecti
2f470 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66  vely known as "f
2f480 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
2f490 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61   routines").** a
2f4a0 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53  re used to add S
2f4b0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
2f4c0 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f  aggregates or to
2f4d0 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65   redefine the be
2f4e0 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69  havior.** of exi
2f4f0 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69  sting SQL functi
2f500 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
2f510 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66  s.  The only dif
2f520 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e  ferences between
2f530 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e  .** these routin
2f540 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20  es are the text 
2f550 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65  encoding expecte
2f560 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63  d for.** the sec
2f570 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74  ond parameter (t
2f580 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66  he name of the f
2f590 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72  unction being cr
2f5a0 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68  eated).** and th
2f5b0 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62  e presence or ab
2f5c0 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72  sence of a destr
2f5d0 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66  uctor callback f
2f5e0 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  or.** the applic
2f5f0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
2f600 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  er..**.** ^The f
2f610 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
2f620 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
2f630 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77  connection] to w
2f640 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20  hich the SQL.** 
2f650 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62  function is to b
2f660 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e  e added.  ^If an
2f670 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65   application use
2f680 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
2f690 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
2f6a0 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c  ection then appl
2f6b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2f6c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75  SQL functions mu
2f6d0 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74  st be added.** t
2f6e0 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
2f6f0 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72  connection separ
2f700 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ately..**.** ^Th
2f710 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2f720 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
2f730 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
2f740 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64  on to be created
2f750 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64   or.** redefined
2f760 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f  .  ^The length o
2f770 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69  f the name is li
2f780 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74  mited to 255 byt
2f790 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a  es in a UTF-8.**
2f7a0 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c   representation,
2f7b0 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68   exclusive of th
2f7c0 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  e zero-terminato
2f7d0 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  r.  ^Note that t
2f7e0 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74  he name.** lengt
2f7f0 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54  h limit is in UT
2f800 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63  F-8 bytes, not c
2f810 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54  haracters nor UT
2f820 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a  F-16 bytes.  .**
2f830 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f   ^Any attempt to
2f840 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69   create a functi
2f850 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72  on with a longer
2f860 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65   name.** will re
2f870 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f  sult in [SQLITE_
2f880 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65  MISUSE] being re
2f890 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
2f8a0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2f8b0 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20  er (nArg).** is 
2f8c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
2f8d0 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65  guments that the
2f8e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
2f8f0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61  .** aggregate ta
2f900 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61  kes. ^If this pa
2f910 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74  rameter is -1, t
2f920 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hen the SQL func
2f930 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
2f940 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e  gate may take an
2f950 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
2f960 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20  ments between 0 
2f970 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a  and the limit.**
2f980 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33   set by [sqlite3
2f990 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f  _limit]([SQLITE_
2f9a0 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
2f9b0 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68  RG]).  If the th
2f9c0 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
2f9d0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31   is less than -1
2f9e0 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
2f9f0 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65   127 then the be
2fa00 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64  havior is.** und
2fa10 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
2fa20 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2fa30 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73  ter, eTextRep, s
2fa40 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a  pecifies what.**
2fa50 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
2fa60 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74  text encoding] t
2fa70 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  his SQL function
2fa80 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20   prefers for.** 
2fa90 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20  its parameters. 
2faa0 20 45 76 65 72 79 20 53 51 4c 20 66 75 6e 63 74   Every SQL funct
2fab0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
2fac0 6f 6e 20 6d 75 73 74 20 62 65 20 61 62 6c 65 20  on must be able 
2fad0 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20  to work.** with 
2fae0 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c  UTF-8, UTF-16le,
2faf0 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42   or UTF-16be.  B
2fb00 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e  ut some implemen
2fb10 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a  tations may be.*
2fb20 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74  * more efficient
2fb30 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69   with one encodi
2fb40 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e  ng than another.
2fb50 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f    ^An applicatio
2fb60 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20  n may.** invoke 
2fb70 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2fb80 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c  unction() or sql
2fb90 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2fba0 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c  tion16() multipl
2fbb0 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20  e.** times with 
2fbc0 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
2fbd0 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65  n but with diffe
2fbe0 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65  rent values of e
2fbf0 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65  TextRep..** ^Whe
2fc00 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  n multiple imple
2fc10 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
2fc20 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
2fc30 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53  are available, S
2fc40 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69  QLite.** will pi
2fc50 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20  ck the one that 
2fc60 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61  involves the lea
2fc70 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
2fc80 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  a conversion..**
2fc90 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c   If there is onl
2fca0 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65  y a single imple
2fcb0 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20  mentation which 
2fcc0 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68  does not care wh
2fcd0 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64  at text.** encod
2fce0 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
2fcf0 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
2fd00 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
2fd10 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a  [SQLITE_ANY]..**
2fd20 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20  .** ^(The fifth 
2fd30 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20  parameter is an 
2fd40 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65  arbitrary pointe
2fd50 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  r.  The implemen
2fd60 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  tation of the.**
2fd70 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61   function can ga
2fd80 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69  in access to thi
2fd90 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20  s pointer using 
2fda0 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
2fdb0 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ta()].)^.**.** ^
2fdc0 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e  The sixth, seven
2fdd0 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61  th and eighth pa
2fde0 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c  rameters, xFunc,
2fdf0 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
2fe00 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65  l, are.** pointe
2fe10 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65  rs to C-language
2fe20 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
2fe30 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
2fe40 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
2fe50 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73   aggregate. ^A s
2fe60 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
2fe70 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
2fe80 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2fe90 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61   the xFunc.** ca
2fea0 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c  llback only; NUL
2feb0 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20  L pointers must 
2fec0 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
2fed0 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
2fee0 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  l.** parameters.
2fef0 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53   ^An aggregate S
2ff00 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
2ff10 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
2ff20 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a  tation of xStep.
2ff30 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e  ** and xFinal an
2ff40 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d  d NULL pointer m
2ff50 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f  ust be passed fo
2ff60 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c  r xFunc. ^To del
2ff70 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a  ete an existing.
2ff80 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
2ff90 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61  or aggregate, pa
2ffa0 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  ss NULL pointers
2ffb0 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66   for all three f
2ffc0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  unction.** callb
2ffd0 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  acks..**.** ^(If
2ffe0 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d   the ninth param
2fff0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
30000 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
30010 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  v2() is not NULL
30020 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
30030 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
30040 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
30050 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a  ata pointer. .**
30060 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   The destructor 
30070 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
30080 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
30090 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20  deleted, either 
300a0 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72  by being.** over
300b0 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74  loaded or when t
300c0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
300d0 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e  ection closes.)^
300e0 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63  .** ^The destruc
300f0 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f  tor is also invo
30100 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ked if the call 
30110 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  to.** sqlite3_cr
30120 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
30130 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68  () fails..** ^Wh
30140 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  en the destructo
30150 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  r callback of th
30160 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65  e tenth paramete
30170 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74  r is invoked, it
30180 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20  .** is passed a 
30190 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
301a0 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20  which is a copy 
301b0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
301c0 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e  on data .** poin
301d0 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68  ter which was th
301e0 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
301f0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
30200 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
30210 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  )..**.** ^It is 
30220 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67  permitted to reg
30230 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69  ister multiple i
30240 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
30250 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75  f the same.** fu
30260 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65  nctions with the
30270 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77   same name but w
30280 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65  ith either diffe
30290 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a  ring numbers of.
302a0 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  ** arguments or 
302b0 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72  differing prefer
302c0 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
302d0 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  gs.  ^SQLite wil
302e0 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70  l use.** the imp
302f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74  lementation that
30300 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61   most closely ma
30310 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e  tches the way in
30320 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51   which the.** SQ
30330 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  L function is us
30340 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  ed.  ^A function
30350 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
30360 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  with a non-negat
30370 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61  ive.** nArg para
30380 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65  meter is a bette
30390 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
303a0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
303b0 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61  tation with.** a
303c0 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20   negative nArg. 
303d0 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
303e0 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64  re the preferred
303f0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a   text encoding.*
30400 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61  * matches the da
30410 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20  tabase encoding 
30420 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d  is a better.** m
30430 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
30440 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
30450 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65  ncoding is diffe
30460 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75  rent.  .** ^A fu
30470 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
30480 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
30490 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20  ence is between 
304a0 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31  UTF16le and UTF1
304b0 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73  6be.** is a clos
304c0 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
304d0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
304e0 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
304f0 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74  erence is.** bet
30500 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54  ween UTF8 and UT
30510 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c  F16..**.** ^Buil
30520 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d  t-in functions m
30530 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  ay be overloaded
30540 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74   by new applicat
30550 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
30560 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  tions..**.** ^An
30570 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
30580 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
30590 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61   permitted to ca
305a0 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ll other.** SQLi
305b0 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20  te interfaces.  
305c0 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61  However, such ca
305d0 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20  lls must not.** 
305e0 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
305f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f  se connection no
30600 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65  r finalize or re
30610 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
30620 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  .** statement in
30630 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74   which the funct
30640 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
30650 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
30660 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a  reate_function(.
30670 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
30680 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
30690 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
306a0 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
306b0 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
306c0 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
306d0 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
306e0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
306f0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
30700 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
30710 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
30720 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
30730 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
30740 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
30750 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  text*).);.int sq
30760 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
30770 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ction16(.  sqlit
30780 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
30790 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  void *zFunctionN
307a0 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
307b0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
307c0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
307d0 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
307e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
307f0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
30800 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
30810 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
30820 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
30830 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
30840 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
30850 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
30860 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
30870 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
30880 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
30890 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
308a0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
308b0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
308c0 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
308d0 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
308e0 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
308f0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
30900 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
30910 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
30920 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
30930 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
30940 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
30950 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
30960 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69  context*),.  voi
30970 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69  d(*xDestroy)(voi
30980 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*).);../*.** CA
30990 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63  PI3REF: Text Enc
309a0 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65  odings.**.** The
309b0 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69  se constant defi
309c0 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73  ne integer codes
309d0 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20   that represent 
309e0 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74  the various.** t
309f0 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75  ext encodings su
30a00 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
30a10 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
30a20 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20  LITE_UTF8       
30a30 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
30a40 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20  LITE_UTF16LE    
30a50 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
30a60 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20  LITE_UTF16BE    
30a70 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
30a80 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20  LITE_UTF16      
30a90 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20      4    /* Use 
30aa0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
30ab0 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
30ac0 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20  ITE_ANY         
30ad0 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74     5    /* sqlit
30ae0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
30af0 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  on only */.#defi
30b00 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  ne SQLITE_UTF16_
30b10 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a  ALIGNED  8    /*
30b20 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
30b30 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a  collation only *
30b40 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
30b50 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75  F: Deprecated Fu
30b60 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45  nctions.** DEPRE
30b70 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73  CATED.**.** Thes
30b80 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
30b90 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49  [deprecated].  I
30ba0 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74  n order to maint
30bb0 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ain.** backwards
30bc0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77   compatibility w
30bd0 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20  ith older code, 
30be0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
30bf0 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20  continue .** to 
30c00 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48  be supported.  H
30c10 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c  owever, new appl
30c20 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
30c30 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65  avoid.** the use
30c40 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
30c50 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e  ons.  To help en
30c60 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74  courage people t
30c70 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67  o avoid.** using
30c80 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
30c90 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69  , we are not goi
30ca0 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77  ng to tell you w
30cb0 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a  hat they do..*/.
30cc0 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f  #ifndef SQLITE_O
30cd0 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53  MIT_DEPRECATED.S
30ce0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
30cf0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67   int sqlite3_agg
30d00 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c  regate_count(sql
30d10 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
30d20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
30d30 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  D int sqlite3_ex
30d40 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74  pired(sqlite3_st
30d50 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
30d60 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
30d70 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e  te3_transfer_bin
30d80 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
30d90 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  mt*, sqlite3_stm
30da0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
30db0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
30dc0 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65  e3_global_recove
30dd0 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  r(void);.SQLITE_
30de0 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
30df0 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63  sqlite3_thread_c
30e00 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51  leanup(void);.SQ
30e10 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
30e20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  int sqlite3_memo
30e30 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29  ry_alarm(void(*)
30e40 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  (void*,sqlite3_i
30e50 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20  nt64,int),.     
30e60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30e70 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69   void*,sqlite3_i
30e80 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt64);.#endif../
30e90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
30ea0 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e  btaining SQL Fun
30eb0 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20  ction Parameter 
30ec0 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65  Values.**.** The
30ed0 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c   C-language impl
30ee0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51  ementation of SQ
30ef0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
30f00 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a  aggregates uses.
30f10 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69  ** this set of i
30f20 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65  nterface routine
30f30 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
30f40 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73  parameter values
30f50 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74   on.** the funct
30f60 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
30f70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e  ..**.** The xFun
30f80 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75  c (for scalar fu
30f90 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65  nctions) or xSte
30fa0 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65  p (for aggregate
30fb0 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  s) parameters.**
30fc0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
30fd0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
30fe0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
30ff0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
31000 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c  ].** define call
31010 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65  backs that imple
31020 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
31030 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
31040 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72  gates..** The 3r
31050 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
31060 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69  hese callbacks i
31070 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
31080 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72  inters to.** [pr
31090 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
310a0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20  value] objects. 
310b0 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73   There is one [s
310c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
310d0 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ject for.** each
310e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
310f0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20  e SQL function. 
31100 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
31110 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65  are used to.** e
31120 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72  xtract values fr
31130 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
31140 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
31150 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
31160 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77  ines work only w
31170 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73  ith [protected s
31180 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
31190 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74  jects..** Any at
311a0 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
311b0 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61  se routines on a
311c0 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  n [unprotected s
311d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
311e0 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20   object results 
311f0 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
31200 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  avior..**.** ^Th
31210 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
31220 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20  k just like the 
31230 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63  corresponding [c
31240 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
31250 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70  ctions].** excep
31260 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f  t that  these ro
31270 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69  utines take a si
31280 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20  ngle [protected 
31290 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
312a0 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72  bject.** pointer
312b0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73   instead of a [s
312c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f  qlite3_stmt*] po
312d0 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74  inter and an int
312e0 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  eger column numb
312f0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
31300 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
31310 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20  t16() interface 
31320 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31  extracts a UTF-1
31330 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74  6 string.** in t
31340 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f  he native byte-o
31350 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74  rder of the host
31360 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a   machine.  ^The.
31370 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
31380 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20  _text16be() and 
31390 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
313a0 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61  xt16le() interfa
313b0 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55  ces.** extract U
313c0 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73  TF-16 strings as
313d0 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20   big-endian and 
313e0 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65  little-endian re
313f0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
31400 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
31410 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
31420 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  pe() interface a
31430 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79  ttempts to apply
31440 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69  .** numeric affi
31450 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75  nity to the valu
31460 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74  e.  This means t
31470 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69  hat an attempt i
31480 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e  s.** made to con
31490 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74  vert the value t
314a0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20  o an integer or 
314b0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20  floating point. 
314c0 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f   If.** such a co
314d0 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73  nversion is poss
314e0 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73  ible without los
314f0 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  s of information
31500 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f   (in other.** wo
31510 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75  rds, if the valu
31520 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68  e is a string th
31530 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20  at looks like a 
31540 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20  number).** then 
31550 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  the conversion i
31560 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74  s performed.  Ot
31570 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65  herwise no conve
31580 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a  rsion occurs..**
31590 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54   The [SQLITE_INT
315a0 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d  EGER | datatype]
315b0 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f   after conversio
315c0 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
315d0 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61  .**.** Please pa
315e0 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74  y particular att
315f0 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61  ention to the fa
31600 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e  ct that the poin
31610 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ter returned.** 
31620 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
31630 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  lue_blob()], [sq
31640 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
31650 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
31660 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
31670 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c  ()] can be inval
31680 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73  idated by a subs
31690 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  equent call to.*
316a0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
316b0 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69  _bytes()], [sqli
316c0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
316d0 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  6()], [sqlite3_v
316e0 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
316f0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
31700 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a  ue_text16()]..**
31710 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
31720 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
31730 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
31740 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65  thread as.** the
31750 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68   SQL function th
31760 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20  at supplied the 
31770 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d  [sqlite3_value*]
31780 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a   parameters..*/.
31790 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
317a0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73  te3_value_blob(s
317b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
317c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
317d0 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  e_bytes(sqlite3_
317e0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
317f0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
31800 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
31810 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  *);.double sqlit
31820 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28  e3_value_double(
31830 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
31840 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
31850 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76  ue_int(sqlite3_v
31860 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f  alue*);.sqlite3_
31870 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61  int64 sqlite3_va
31880 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  lue_int64(sqlite
31890 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
318a0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
318b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
318c0 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  xt(sqlite3_value
318d0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
318e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
318f0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  xt16(sqlite3_val
31900 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
31910 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
31920 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
31930 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
31940 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
31950 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c  lue_text16be(sql
31960 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
31970 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
31980 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
31990 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
319a0 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
319b0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
319c0 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
319d0 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67  I3REF: Obtain Ag
319e0 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e  gregate Function
319f0 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49   Context.**.** I
31a00 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
31a10 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  f aggregate SQL 
31a20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68  functions use th
31a30 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f  is.** routine to
31a40 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
31a50 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65   for storing the
31a60 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ir state..**.** 
31a70 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20  ^The first time 
31a80 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  the sqlite3_aggr
31a90 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
31aa0 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  N) routine is ca
31ab0 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70  lled .** for a p
31ac0 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67  articular aggreg
31ad0 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51  ate function, SQ
31ae0 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  Lite.** allocate
31af0 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a  s N of memory, z
31b00 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d  eroes out that m
31b10 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72  emory, and retur
31b20 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  ns a pointer.** 
31b30 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72  to the new memor
31b40 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e  y. ^On second an
31b50 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  d subsequent cal
31b60 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
31b70 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
31b80 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d  xt() for the sam
31b90 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
31ba0 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a  tion instance,.*
31bb0 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65  * the same buffe
31bc0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  r is returned.  
31bd0 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  Sqlite3_aggregat
31be0 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e  e_context() is n
31bf0 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  ormally.** calle
31c00 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
31c10 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68  invocation of th
31c20 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b  e xStep callback
31c30 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a   and then one.**
31c40 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20   last time when 
31c50 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62  the xFinal callb
31c60 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ack is invoked. 
31c70 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20   ^(When no rows 
31c80 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72  match.** an aggr
31c90 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65  egate query, the
31ca0 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63   xStep() callbac
31cb0 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61  k of the aggrega
31cc0 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69  te function.** i
31cd0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
31ce0 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e   never called an
31cf0 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61  d xFinal() is ca
31d00 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63  lled exactly onc
31d10 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63  e..** In those c
31d20 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67  ases, sqlite3_ag
31d30 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
31d40 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65  ) might be calle
31d50 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72  d for the.** fir
31d60 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74  st time from wit
31d70 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a  hin xFinal().)^.
31d80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
31d90 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
31da0 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
31db0 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  e returns a NULL
31dc0 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65   pointer .** whe
31dd0 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20 69  n first called i
31de0 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
31df0 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
31e00 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79  o or if a memory
31e10 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72 72  .** allocate err
31e20 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a  or occurs..**.**
31e30 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66   ^(The amount of
31e40 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64   space allocated
31e50 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72   by sqlite3_aggr
31e60 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
31e70 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69  N) is.** determi
31e80 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72  ned by the N par
31e90 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20  ameter on first 
31ea0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e  successful call.
31eb0 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a    Changing the.*
31ec0 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20  * value of N in 
31ed0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
31ee0 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  to sqlite3_aggre
31ef0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77  gate_context() w
31f00 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d  ithin.** the sam
31f10 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
31f20 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69  tion instance wi
31f30 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68  ll not resize th
31f40 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
31f50 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69  cation.)^  Withi
31f60 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c  n the xFinal cal
31f70 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75 73  lback, it is cus
31f80 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a  tomary to set.**
31f90 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f   N=0 in calls to
31fa0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
31fb0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
31fc0 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70  so that no .** p
31fd0 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20  ointless memory 
31fe0 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75  allocations occu
31ff0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  r..**.** ^SQLite
32000 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66   automatically f
32010 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  rees the memory 
32020 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a  allocated by .**
32030 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
32040 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65  te_context() whe
32050 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  n the aggregate 
32060 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e  query concludes.
32070 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
32080 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
32090 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  be a copy of the
320a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
320b0 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74  text | SQL funct
320c0 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61  ion context] tha
320d0 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  t is the first p
320e0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
320f0 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e  he xStep or xFin
32100 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74  al callback rout
32110 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ine that impleme
32120 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74  nts the aggregat
32130 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  e.** function..*
32140 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
32150 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
32160 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
32170 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
32180 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  * the aggregate 
32190 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
321a0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
321b0 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   *sqlite3_aggreg
321c0 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69  ate_context(sqli
321d0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
321e0 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a  t nBytes);../*.*
321f0 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72  * CAPI3REF: User
32200 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69   Data For Functi
32210 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ons.**.** ^The s
32220 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
32230 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
32240 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
32250 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68  * the pointer th
32260 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72  at was the pUser
32270 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28  Data parameter (
32280 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
32290 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
322a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
322b0 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
322c0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
322d0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
322e0 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
322f0 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
32300 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
32310 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
32320 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
32330 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
32340 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
32350 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
32360 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70   which.** the ap
32370 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
32380 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  d function is ru
32390 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
323a0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
323b0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
323c0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
323d0 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
323e0 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75  onnection For Fu
323f0 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54  nctions.**.** ^T
32400 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  he sqlite3_conte
32410 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69  xt_db_handle() i
32420 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
32430 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
32440 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
32450 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
32460 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20  ction] (the 1st 
32470 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
32480 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
32490 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
324a0 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
324b0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
324c0 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
324d0 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
324e0 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
324f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
32500 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
32510 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74  /.sqlite3 *sqlit
32520 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
32530 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ndle(sqlite3_con
32540 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
32550 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f  API3REF: Functio
32560 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61  n Auxiliary Data
32570 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
32580 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73  ctions may be us
32590 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65  ed by (non-aggre
325a0 67 61 74 65 29 20 53 51 4c 20 66 75 6e 63 74 69  gate) SQL functi
325b0 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69  ons to.** associ
325c0 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74  ate metadata wit
325d0 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65  h argument value
325e0 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76  s. If the same v
325f0 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74  alue is passed t
32600 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e  o.** multiple in
32610 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
32620 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69   same SQL functi
32630 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20  on during query 
32640 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72  execution, under
32650 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73  .** some circums
32660 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63  tances the assoc
32670 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d  iated metadata m
32680 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e  ay be preserved.
32690 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20    An example.** 
326a0 6f 66 20 77 68 65 72 65 20 74 68 69 73 20 6d 69  of where this mi
326b0 67 68 74 20 62 65 20 75 73 65 66 75 6c 20 69 73  ght be useful is
326c0 20 69 6e 20 61 20 72 65 67 75 6c 61 72 2d 65 78   in a regular-ex
326d0 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e  pression matchin
326e0 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54  g.** function. T
326f0 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73  he compiled vers
32700 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c  ion of the regul
32710 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  ar expression ca
32720 6e 20 62 65 20 73 74 6f 72 65 64 20 61 73 0a 2a  n be stored as.*
32730 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  * metadata assoc
32740 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 70  iated with the p
32750 61 74 74 65 72 6e 20 73 74 72 69 6e 67 2e 20 20  attern string.  
32760 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e 67  .** Then as long
32770 20 61 73 20 74 68 65 20 70 61 74 74 65 72 6e 20   as the pattern 
32780 73 74 72 69 6e 67 20 72 65 6d 61 69 6e 73 20 74  string remains t
32790 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 20  he same,.** the 
327a0 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72  compiled regular
327b0 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
327c0 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c  be reused on mul
327d0 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  tiple.** invocat
327e0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
327f0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
32800 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
32810 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
32820 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
32830 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
32840 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63  etadata.** assoc
32850 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  iated by the sql
32860 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
32870 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  () function with
32880 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e   the Nth argumen
32890 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68  t.** value to th
328a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
328b0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
328c0 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ^If there is no 
328d0 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f  metadata.** asso
328e0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
328f0 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
32900 74 2c 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f  t, this sqlite3_
32910 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
32920 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72  terface.** retur
32930 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
32940 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
32950 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
32960 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 72  a(C,N,P,X) inter
32970 66 61 63 65 20 73 61 76 65 73 20 50 20 61 73 20  face saves P as 
32980 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65  metadata for the
32990 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e   N-th.** argumen
329a0 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
329b0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
329c0 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71 75  ction.  ^Subsequ
329d0 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
329e0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
329f0 61 74 61 28 43 2c 4e 29 20 72 65 74 75 72 6e 20  ata(C,N) return 
32a00 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74 20  P from the most 
32a10 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74 65  recent.** sqlite
32a20 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
32a30 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69 66 20 74  N,P,X) call if t
32a40 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 73  he metadata is s
32a50 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a 2a  till valid or.**
32a60 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 6d 65 74   NULL if the met
32a70 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 64  adata has been d
32a80 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41 66  iscarded..** ^Af
32a90 74 65 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f  ter each call to
32aa0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
32ab0 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77 68  data(C,N,P,X) wh
32ac0 65 72 65 20 58 20 69 73 20 6e 6f 74 20 4e 55 4c  ere X is not NUL
32ad0 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  L,.** SQLite wil
32ae0 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
32af0 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e  tructor function
32b00 20 58 20 77 69 74 68 20 70 61 72 61 6d 65 74 65   X with paramete
32b10 72 20 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20 6f  r P exactly.** o
32b20 6e 63 65 2c 20 77 68 65 6e 20 74 68 65 20 6d 65  nce, when the me
32b30 74 61 64 61 74 61 20 69 73 20 64 69 73 63 61 72  tadata is discar
32b40 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ded..** SQLite i
32b50 73 20 66 72 65 65 20 74 6f 20 64 69 73 63 61 72  s free to discar
32b60 64 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 61  d the metadata a
32b70 74 20 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63 6c  t any time, incl
32b80 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c  uding: <ul>.** <
32b90 6c 69 3e 20 77 68 65 6e 20 74 68 65 20 63 6f 72  li> when the cor
32ba0 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74  responding funct
32bb0 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68  ion parameter ch
32bc0 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  anges, or.** <li
32bd0 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  > when [sqlite3_
32be0 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
32bf0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
32c00 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 74   is called for t
32c10 68 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20 73  he.**      SQL s
32c20 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20  tatement, or.** 
32c30 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c 69 74 65  <li> when sqlite
32c40 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
32c50 69 73 20 69 6e 76 6f 6b 65 64 20 61 67 61 69 6e  is invoked again
32c60 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 70 61 72   on the same par
32c70 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c  ameter, or.** <l
32c80 69 3e 20 64 75 72 69 6e 67 20 74 68 65 20 6f 72  i> during the or
32c90 69 67 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f 73  iginal sqlite3_s
32ca0 65 74 5f 61 75 78 64 61 74 61 28 29 20 63 61 6c  et_auxdata() cal
32cb0 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79 20  l when a memory 
32cc0 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61 74  .**      allocat
32cd0 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
32ce0 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  . </ul>)^.**.** 
32cf0 4e 6f 74 65 20 74 68 65 20 6c 61 73 74 20 62 75  Note the last bu
32d00 6c 6c 65 74 20 69 6e 20 70 61 72 74 69 63 75 6c  llet in particul
32d10 61 72 2e 20 20 54 68 65 20 64 65 73 74 72 75 63  ar.  The destruc
32d20 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71 6c  tor X in .** sql
32d30 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
32d40 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74 20  (C,N,P,X) might 
32d50 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64 69  be called immedi
32d60 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 68  ately, before th
32d70 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74  e.** sqlite3_set
32d80 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
32d90 66 61 63 65 20 65 76 65 6e 20 72 65 74 75 72 6e  face even return
32da0 73 2e 20 20 48 65 6e 63 65 20 73 71 6c 69 74 65  s.  Hence sqlite
32db0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 0a  3_set_auxdata().
32dc0 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 63 61 6c  ** should be cal
32dd0 6c 65 64 20 6e 65 61 72 20 74 68 65 20 65 6e 64  led near the end
32de0 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
32df0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
32e00 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74  and the.** funct
32e10 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
32e20 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61  on should not ma
32e30 6b 65 20 61 6e 79 20 75 73 65 20 6f 66 20 50 20  ke any use of P 
32e40 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65 33  after.** sqlite3
32e50 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 68  _set_auxdata() h
32e60 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a  as been called..
32e70 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74  **.** ^(In pract
32e80 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73  ice, metadata is
32e90 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65   preserved betwe
32ea0 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  en function call
32eb0 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  s for.** functio
32ec0 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61  n parameters tha
32ed0 74 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74 69  t are compile-ti
32ee0 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69 6e  me constants, in
32ef0 63 6c 75 64 69 6e 67 20 6c 69 74 65 72 61 6c 0a  cluding literal.
32f00 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70  ** values and [p
32f10 61 72 61 6d 65 74 65 72 73 5d 20 61 6e 64 20 65  arameters] and e
32f20 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70 6f  xpressions compo
32f30 73 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  sed from the sam
32f40 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  e.)^.**.** These
32f50 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
32f60 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
32f70 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
32f80 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
32f90 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
32fa0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
32fb0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
32fc0 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
32fd0 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f  ext*, int N);.vo
32fe0 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  id sqlite3_set_a
32ff0 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
33000 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20  ontext*, int N, 
33010 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28  void*, void (*)(
33020 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  void*));.../*.**
33030 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74   CAPI3REF: Const
33040 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70  ants Defining Sp
33050 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72  ecial Destructor
33060 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20   Behavior.**.** 
33070 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61  These are specia
33080 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65  l values for the
33090 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74   destructor that
330a0 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73   is passed in as
330b0 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72   the.** final ar
330c0 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e  gument to routin
330d0 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
330e0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e  _result_blob()].
330f0 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75    ^If the destru
33100 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ctor.** argument
33110 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49   is SQLITE_STATI
33120 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  C, it means that
33130 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69   the content poi
33140 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74  nter is constant
33150 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76  .** and will nev
33160 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64  er change.  It d
33170 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
33180 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e  be destroyed.  ^
33190 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52  The.** SQLITE_TR
331a0 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65  ANSIENT value me
331b0 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
331c0 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  tent will likely
331d0 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68   change in.** th
331e0 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e  e near future an
331f0 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68  d that SQLite sh
33200 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77  ould make its ow
33210 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
33220 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
33230 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
33240 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70  g..**.** The typ
33250 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72  edef is necessar
33260 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  y to work around
33270 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72   problems in cer
33280 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70  tain.** C++ comp
33290 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  ilers..*/.typede
332a0 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
332b0 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
332c0 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e  )(void*);.#defin
332d0 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20  e SQLITE_STATIC 
332e0 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64       ((sqlite3_d
332f0 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30  estructor_type)0
33300 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
33310 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73  _TRANSIENT   ((s
33320 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
33330 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a  r_type)-1)../*.*
33340 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74  * CAPI3REF: Sett
33350 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f  ing The Result O
33360 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f  f An SQL Functio
33370 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  n.**.** These ro
33380 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
33390 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20  by the xFunc or 
333a0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73  xFinal callbacks
333b0 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65   that.** impleme
333c0 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  nt SQL functions
333d0 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
333e0 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    See.** [sqlite
333f0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
33400 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
33410 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
33420 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64  n16()].** for ad
33430 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
33440 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion..**.** Thes
33450 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b  e functions work
33460 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20   very much like 
33470 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62  the [parameter b
33480 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f  inding] family o
33490 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75  f.** functions u
334a0 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75  sed to bind valu
334b0 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d  es to host param
334c0 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65  eters in prepare
334d0 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  d statements..**
334e0 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53   Refer to the [S
334f0 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f  QL parameter] do
33500 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
33510 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
33520 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  mation..**.** ^T
33530 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
33540 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  t_blob() interfa
33550 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
33560 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
33570 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
33580 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
33590 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20   the BLOB whose 
335a0 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74  content is point
335b0 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20  ed.** to by the 
335c0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
335d0 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20   and which is N 
335e0 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65  bytes long where
335f0 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69   N is the.** thi
33600 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
33610 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
33620 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
33630 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65  () interfaces se
33640 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  t the result of.
33650 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
33660 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
33670 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42  ion to be a BLOB
33680 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20   containing all 
33690 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e  zero.** bytes an
336a0 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  d N bytes in siz
336b0 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  e, where N is th
336c0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32  e value of the 2
336d0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  nd parameter..**
336e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
336f0 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29  _result_double()
33700 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
33710 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
33720 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
33730 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
33740 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74  on to be a float
33750 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20  ing point value 
33760 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
33770 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  its 2nd argument
33780 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
33790 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
337a0 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
337b0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
337c0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61   functions.** ca
337d0 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  use the implemen
337e0 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ted SQL function
337f0 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63   to throw an exc
33800 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69  eption..** ^SQLi
33810 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69  te uses the stri
33820 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ng pointed to by
33830 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61   the.** 2nd para
33840 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
33850 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
33860 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
33870 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61  t_error16().** a
33880 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e  s the text of an
33890 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20   error message. 
338a0 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72   ^SQLite interpr
338b0 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a  ets the error.**
338c0 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
338d0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
338e0 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55  ult_error() as U
338f0 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a  TF-8. ^SQLite.**
33900 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
33910 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
33920 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33930 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69  16() as UTF-16 i
33940 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65  n native.** byte
33950 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65   order.  ^If the
33960 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
33970 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
33980 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
33990 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
339a0 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67  error16() is neg
339b0 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
339c0 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65  e takes as the e
339d0 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
339e0 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f  all text up thro
339f0 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
33a00 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
33a10 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
33a20 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
33a30 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33a40 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
33a50 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
33a60 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  ) is non-negativ
33a70 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
33a80 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a  kes that many.**
33a90 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
33aa0 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65  acters) from the
33ab0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
33ac0 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  s the error mess
33ad0 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  age..** ^The sql
33ae0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
33af0 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
33b00 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
33b10 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b  .** routines mak
33b20 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79  e a private copy
33b30 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65   of the error me
33b40 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72  ssage text befor
33b50 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e  e.** they return
33b60 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61  .  Hence, the ca
33b70 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  lling function c
33b80 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72  an deallocate or
33b90 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74  .** modify the t
33ba0 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72  ext after they r
33bb0 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61  eturn without ha
33bc0 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  rm..** ^The sqli
33bd0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33be0 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e  _code() function
33bf0 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72   changes the err
33c00 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72  or code.** retur
33c10 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73  ned by SQLite as
33c20 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20   a result of an 
33c30 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74  error in a funct
33c40 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c  ion.  ^By defaul
33c50 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20  t,.** the error 
33c60 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45  code is SQLITE_E
33c70 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71  RROR.  ^A subseq
33c80 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
33c90 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
33ca0 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
33cb0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
33cc0 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72  () resets the er
33cd0 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49  ror code to SQLI
33ce0 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20  TE_ERROR..**.** 
33cf0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
33d00 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67  ult_error_toobig
33d10 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
33d20 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
33d30 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20  row an.** error 
33d40 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
33d50 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
33d60 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20   is too long to 
33d70 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a  represent..**.**
33d80 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
33d90 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
33da0 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
33db0 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
33dc0 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20  row an.** error 
33dd0 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
33de0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
33df0 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a  ion failed..**.*
33e00 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
33e10 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65  esult_int() inte
33e20 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
33e30 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
33e40 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
33e50 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
33e60 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d  on to be the 32-
33e70 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
33e80 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
33e90 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
33ea0 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73  ument..** ^The s
33eb0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
33ec0 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20  t64() interface 
33ed0 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
33ee0 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
33ef0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
33f00 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
33f10 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69  be the 64-bit si
33f20 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
33f30 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
33f40 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
33f50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
33f60 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
33f70 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
33f80 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
33f90 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
33fa0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
33fb0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e  function to be N
33fc0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
33fd0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
33fe0 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  ext(), sqlite3_r
33ff0 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a  esult_text16(),.
34000 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
34010 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e  t_text16le(), an
34020 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
34030 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65  _text16be() inte
34040 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68  rfaces.** set th
34050 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
34060 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
34070 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
34080 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65  on to be.** a te
34090 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20  xt string which 
340a0 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61  is represented a
340b0 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20  s UTF-8, UTF-16 
340c0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
340d0 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74  r,.** UTF-16 lit
340e0 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55  tle endian, or U
340f0 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e  TF-16 big endian
34100 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  , respectively..
34110 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73  ** ^SQLite takes
34120 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74   the text result
34130 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63   from the applic
34140 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68  ation from.** th
34150 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
34160 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  of the sqlite3_r
34170 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
34180 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74  rfaces..** ^If t
34190 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
341a0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
341b0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
341c0 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65  erfaces.** is ne
341d0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c  gative, then SQL
341e0 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74  ite takes result
341f0 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32   text from the 2
34200 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
34210 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
34220 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
34230 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64  ..** ^If the 3rd
34240 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
34250 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
34260 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
34270 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  s.** is non-nega
34280 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61  tive, then as ma
34290 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68  ny bytes (not ch
342a0 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65  aracters) of the
342b0 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64   text.** pointed
342c0 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70   to by the 2nd p
342d0 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b  arameter are tak
342e0 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63  en as the applic
342f0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a  ation-defined.**
34300 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74   function result
34310 2e 20 20 49 66 20 74 68 65 20 33 72 64 20 70 61  .  If the 3rd pa
34320 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e  rameter is non-n
34330 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74  egative, then it
34340 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74 68 65 20  .** must be the 
34350 62 79 74 65 20 6f 66 66 73 65 74 20 69 6e 74 6f  byte offset into
34360 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72   the string wher
34370 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e  e the NUL termin
34380 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70  ator would.** ap
34390 70 65 61 72 20 69 66 20 74 68 65 20 73 74 72 69  pear if the stri
343a0 6e 67 20 77 68 65 72 65 20 4e 55 4c 20 74 65 72  ng where NUL ter
343b0 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79  minated.  If any
343c0 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20   NUL characters 
343d0 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20  occur.** in the 
343e0 73 74 72 69 6e 67 20 61 74 20 61 20 62 79 74 65  string at a byte
343f0 20 6f 66 66 73 65 74 20 74 68 61 74 20 69 73 20   offset that is 
34400 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 76 61  less than the va
34410 6c 75 65 20 6f 66 20 74 68 65 20 33 72 64 0a 2a  lue of the 3rd.*
34420 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  * parameter, the
34430 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  n the resulting 
34440 73 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74  string will cont
34450 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
34460 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73  s and the.** res
34470 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f  ult of expressio
34480 6e 73 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20  ns operating on 
34490 73 74 72 69 6e 67 73 20 77 69 74 68 20 65 6d 62  strings with emb
344a0 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e  edded NULs is un
344b0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20  defined..** ^If 
344c0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
344d0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
344e0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
344f0 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
34500 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
34510 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ob is a non-NULL
34520 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
34530 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74  QLite calls that
34540 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20  .** function as 
34550 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f  the destructor o
34560 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  n the text or BL
34570 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69  OB result when i
34580 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65  t has.** finishe
34590 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
345a0 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ult..** ^If the 
345b0 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
345c0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
345d0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
345e0 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71  aces or to.** sq
345f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
34600 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
34610 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
34620 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51  _STATIC, then SQ
34630 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20  Lite.** assumes 
34640 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f 72  that the text or
34650 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20   BLOB result is 
34660 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63  in constant spac
34670 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a  e and does not.*
34680 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65  * copy the conte
34690 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65  nt of the parame
346a0 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64  ter nor call a d
346b0 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65  estructor on the
346c0 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e   content.** when
346d0 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
346e0 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
346f0 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  lt..** ^If the 4
34700 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
34710 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
34720 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
34730 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
34740 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
34750 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
34760 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41  stant SQLITE_TRA
34770 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53  NSIENT.** then S
34780 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
34790 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  py of the result
347a0 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61   into space obta
347b0 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f  ined from.** fro
347c0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
347d0 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72  c()] before it r
347e0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
347f0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
34800 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
34810 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
34820 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
34830 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
34840 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
34850 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b   a copy the.** [
34860 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
34870 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
34880 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  t specified by t
34890 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
348a0 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
348b0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
348c0 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65  ) interface make
348d0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
348e0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a  [sqlite3_value].
348f0 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b  ** so that the [
34900 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73  sqlite3_value] s
34910 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
34920 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68  parameter may ch
34930 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65  ange or.** be de
34940 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20  allocated after 
34950 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
34960 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77  alue() returns w
34970 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
34980 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ^A [protected sq
34990 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
349a0 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62  ect may always b
349b0 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a  e used where an.
349c0 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
349d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
349e0 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65  bject is require
349f0 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20  d, so either.** 
34a00 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33  kind of [sqlite3
34a10 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63  _value] object c
34a20 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20  an be used with 
34a30 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a  this interface..
34a40 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72  **.** If these r
34a50 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
34a60 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74  ed from within t
34a70 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  he different thr
34a80 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20  ead.** than the 
34a90 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  one containing t
34aa0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
34ab0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
34ac0 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a  that received.**
34ad0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
34ae0 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20  ntext] pointer, 
34af0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
34b00 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f  undefined..*/.vo
34b10 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
34b20 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  t_blob(sqlite3_c
34b30 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
34b40 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
34b50 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
34b60 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34b70 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63  double(sqlite3_c
34b80 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29  ontext*, double)
34b90 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
34ba0 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69  esult_error(sqli
34bb0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
34bc0 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b  nst char*, int);
34bd0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
34be0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c  sult_error16(sql
34bf0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
34c00 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29  onst void*, int)
34c10 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
34c20 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
34c30 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ig(sqlite3_conte
34c40 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
34c50 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
34c60 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f  nomem(sqlite3_co
34c70 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
34c80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
34c90 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f  or_code(sqlite3_
34ca0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
34cb0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
34cc0 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ult_int(sqlite3_
34cd0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
34ce0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
34cf0 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ult_int64(sqlite
34d00 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69  3_context*, sqli
34d10 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64  te3_int64);.void
34d20 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34d30 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e  null(sqlite3_con
34d40 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
34d50 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
34d60 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
34d70 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
34d80 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
34d90 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
34da0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
34db0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
34dc0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
34dd0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
34de0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
34df0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
34e00 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
34e10 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
34e20 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
34e30 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
34e40 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
34e50 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6be(sqlite3_cont
34e60 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
34e70 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
34e80 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
34e90 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
34ea0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
34eb0 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t*, sqlite3_valu
34ec0 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  e*);.void sqlite
34ed0 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
34ee0 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
34ef0 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  t*, int n);../*.
34f00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66  ** CAPI3REF: Def
34f10 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e  ine New Collatin
34f20 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a  g Sequences.**.*
34f30 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
34f40 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20  ns add, remove, 
34f50 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c  or modify a [col
34f60 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74  lation] associat
34f70 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  ed.** with the [
34f80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
34f90 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61  ion] specified a
34fa0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
34fb0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
34fc0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
34fd0 6c 61 74 69 6f 6e 20 69 73 20 61 20 55 54 46 2d  lation is a UTF-
34fe0 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20  8 string.** for 
34ff0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
35000 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73  ollation() and s
35010 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
35020 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20  llation_v2().** 
35030 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72  and a UTF-16 str
35040 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
35050 74 65 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  te order for sql
35060 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
35070 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43  ation16()..** ^C
35080 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74  ollation names t
35090 68 61 74 20 63 6f 6d 70 61 72 65 20 65 71 75 61  hat compare equa
350a0 6c 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b  l according to [
350b0 73 71 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d 70  sqlite3_strnicmp
350c0 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69  ()] are.** consi
350d0 64 65 72 65 64 20 74 6f 20 62 65 20 74 68 65 20  dered to be the 
350e0 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a  same name..**.**
350f0 20 5e 28 54 68 65 20 74 68 69 72 64 20 61 72 67   ^(The third arg
35100 75 6d 65 6e 74 20 28 65 54 65 78 74 52 65 70 29  ument (eTextRep)
35110 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20   must be one of 
35120 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a  the constants:.*
35130 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
35140 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a  SQLITE_UTF8],.**
35150 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
35160 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  F16LE],.** <li> 
35170 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
35180 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
35190 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20  E_UTF16], or.** 
351a0 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
351b0 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20  16_ALIGNED]..** 
351c0 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20  </ul>)^.** ^The 
351d0 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e  eTextRep argumen
351e0 74 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65  t determines the
351f0 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74 72   encoding of str
35200 69 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a 20 74  ings passed.** t
35210 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  o the collating 
35220 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63  function callbac
35230 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  k, xCallback..**
35240 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54   ^The [SQLITE_UT
35250 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  F16] and [SQLITE
35260 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20  _UTF16_ALIGNED] 
35270 76 61 6c 75 65 73 20 66 6f 72 20 65 54 65 78 74  values for eText
35280 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72  Rep.** force str
35290 69 6e 67 73 20 74 6f 20 62 65 20 55 54 46 31 36  ings to be UTF16
352a0 20 77 69 74 68 20 6e 61 74 69 76 65 20 62 79 74   with native byt
352b0 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65  e order..** ^The
352c0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
352d0 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f  LIGNED] value fo
352e0 72 20 65 54 65 78 74 52 65 70 20 66 6f 72 63 65  r eTextRep force
352f0 73 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 67  s strings to beg
35300 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e  in.** on an even
35310 20 62 79 74 65 20 61 64 64 72 65 73 73 2e 0a 2a   byte address..*
35320 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
35330 20 61 72 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c   argument, pArg,
35340 20 69 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69   is an applicati
35350 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20  on data pointer 
35360 74 68 61 74 20 69 73 20 70 61 73 73 65 64 0a 2a  that is passed.*
35370 2a 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  * through as the
35380 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
35390 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  to the collating
353a0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
353b0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ck..**.** ^The f
353c0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 78  ifth argument, x
353d0 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20 70  Callback, is a p
353e0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ointer to the co
353f0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
35400 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63  ..** ^Multiple c
35410 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
35420 6e 73 20 63 61 6e 20 62 65 20 72 65 67 69 73 74  ns can be regist
35430 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73  ered using the s
35440 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20  ame name but.** 
35450 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 65  with different e
35460 54 65 78 74 52 65 70 20 70 61 72 61 6d 65 74 65  TextRep paramete
35470 72 73 20 61 6e 64 20 53 51 4c 69 74 65 20 77 69  rs and SQLite wi
35480 6c 6c 20 75 73 65 20 77 68 69 63 68 65 76 65 72  ll use whichever
35490 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  .** function req
354a0 75 69 72 65 73 20 74 68 65 20 6c 65 61 73 74 20  uires the least 
354b0 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 74  amount of data t
354c0 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  ransformation..*
354d0 2a 20 5e 49 66 20 74 68 65 20 78 43 61 6c 6c 62  * ^If the xCallb
354e0 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ack argument is 
354f0 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f  NULL then the co
35500 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
35510 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20   is.** deleted. 
35520 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61   ^When all colla
35530 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 68  ting functions h
35540 61 76 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e  aving the same n
35550 61 6d 65 20 61 72 65 20 64 65 6c 65 74 65 64 2c  ame are deleted,
35560 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74 69  .** that collati
35570 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  on is no longer 
35580 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  usable..**.** ^T
35590 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
355a0 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69  ction callback i
355b0 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  s invoked with a
355c0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70 41 72   copy of the pAr
355d0 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  g .** applicatio
355e0 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 61  n data pointer a
355f0 6e 64 20 77 69 74 68 20 74 77 6f 20 73 74 72 69  nd with two stri
35600 6e 67 73 20 69 6e 20 74 68 65 20 65 6e 63 6f 64  ngs in the encod
35610 69 6e 67 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  ing specified.**
35620 20 62 79 20 74 68 65 20 65 54 65 78 74 52 65 70   by the eTextRep
35630 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 20   argument.  The 
35640 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
35650 6f 6e 20 6d 75 73 74 20 72 65 74 75 72 6e 20 61  on must return a
35660 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74 68 61  n.** integer tha
35670 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 7a  t is negative, z
35680 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76 65  ero, or positive
35690 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 72 73 74  .** if the first
356a0 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20   string is less 
356b0 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20  than, equal to, 
356c0 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
356d0 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72  the second,.** r
356e0 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41 20  espectively.  A 
356f0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
35700 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79 73 20 72  on must always r
35710 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 61  eturn the same a
35720 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74  nswer.** given t
35730 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 2e 20  he same inputs. 
35740 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
35750 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
35760 6f 6e 73 20 61 72 65 20 72 65 67 69 73 74 65 72  ons are register
35770 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d  ed.** to the sam
35780 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65  e collation name
35790 20 28 75 73 69 6e 67 20 64 69 66 66 65 72 65 6e   (using differen
357a0 74 20 65 54 65 78 74 52 65 70 20 76 61 6c 75 65  t eTextRep value
357b0 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d  s) then all.** m
357c0 75 73 74 20 67 69 76 65 20 61 6e 20 65 71 75 69  ust give an equi
357d0 76 61 6c 65 6e 74 20 61 6e 73 77 65 72 20 77 68  valent answer wh
357e0 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  en invoked with 
357f0 65 71 75 69 76 61 6c 65 6e 74 20 73 74 72 69 6e  equivalent strin
35800 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61  gs..** The colla
35810 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ting function mu
35820 73 74 20 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c  st obey the foll
35830 6f 77 69 6e 67 20 70 72 6f 70 65 72 74 69 65 73  owing properties
35840 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69   for all.** stri
35850 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a  ngs A, B, and C:
35860 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
35870 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74 68 65 6e  li> If A==B then
35880 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49   B==A..** <li> I
35890 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20  f A==B and B==C 
358a0 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c  then A==C..** <l
358b0 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 54 48 45  i> If A&lt;B THE
358c0 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69  N B&gt;A..** <li
358d0 3e 20 49 66 20 41 26 6c 74 3b 42 20 61 6e 64 20  > If A&lt;B and 
358e0 42 26 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c 74  B&lt;C then A&lt
358f0 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  ;C..** </ol>.**.
35900 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e  ** If a collatin
35910 67 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73  g function fails
35920 20 61 6e 79 20 6f 66 20 74 68 65 20 61 62 6f 76   any of the abov
35930 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e  e constraints an
35940 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74  d that.** collat
35950 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ing function is 
35960 20 72 65 67 69 73 74 65 72 65 64 20 61 6e 64 20   registered and 
35970 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62  used, then the b
35980 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
35990 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65  e.** is undefine
359a0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
359b0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
359c0 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b  lation_v2() work
359d0 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63  s like sqlite3_c
359e0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
359f0 29 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 61 64  ).** with the ad
35a00 64 69 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20  dition that the 
35a10 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63  xDestroy callbac
35a20 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  k is invoked on 
35a30 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65  pArg when.** the
35a40 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
35a50 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2e 0a  ion is deleted..
35a60 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75  ** ^Collating fu
35a70 6e 63 74 69 6f 6e 73 20 61 72 65 20 64 65 6c 65  nctions are dele
35a80 74 65 64 20 77 68 65 6e 20 74 68 65 79 20 61 72  ted when they ar
35a90 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20  e overridden by 
35aa0 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  later.** calls t
35ab0 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  o the collation 
35ac0 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  creation functio
35ad0 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a  ns or when the.*
35ae0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
35af0 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65  ection] is close
35b00 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
35b10 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _close()]..**.**
35b20 20 5e 54 68 65 20 78 44 65 73 74 72 6f 79 20 63   ^The xDestroy c
35b30 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f  allback is <u>no
35b40 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66 20  t</u> called if 
35b50 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  the .** sqlite3_
35b60 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
35b70 5f 76 32 28 29 20 66 75 6e 63 74 69 6f 6e 20 66  _v2() function f
35b80 61 69 6c 73 2e 20 20 41 70 70 6c 69 63 61 74 69  ails.  Applicati
35b90 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a  ons that invoke.
35ba0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
35bb0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
35bc0 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
35bd0 20 78 44 65 73 74 72 6f 79 20 61 72 67 75 6d 65   xDestroy argume
35be0 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68  nt should .** ch
35bf0 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
35c00 6f 64 65 20 61 6e 64 20 64 69 73 70 6f 73 65 20  ode and dispose 
35c10 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
35c20 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 0a  on data pointer.
35c30 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73 20 72 61  ** themselves ra
35c40 74 68 65 72 20 74 68 61 6e 20 65 78 70 65 63 74  ther than expect
35c50 69 6e 67 20 53 51 4c 69 74 65 20 74 6f 20 64 65  ing SQLite to de
35c60 61 6c 20 77 69 74 68 20 69 74 20 66 6f 72 20 74  al with it for t
35c70 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  hem..** This is 
35c80 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 65  different from e
35c90 76 65 72 79 20 6f 74 68 65 72 20 53 51 4c 69 74  very other SQLit
35ca0 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68  e interface.  Th
35cb0 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20  e inconsistency 
35cc0 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e 61  .** is unfortuna
35cd0 74 65 20 62 75 74 20 63 61 6e 6e 6f 74 20 62 65  te but cannot be
35ce0 20 63 68 61 6e 67 65 64 20 77 69 74 68 6f 75 74   changed without
35cf0 20 62 72 65 61 6b 69 6e 67 20 62 61 63 6b 77 61   breaking backwa
35d00 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  rds .** compatib
35d10 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ility..**.** See
35d20 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33   also:  [sqlite3
35d30 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
35d40 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  d()] and [sqlite
35d50 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
35d60 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ed16()]..*/.int 
35d70 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
35d80 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69  ollation(.  sqli
35d90 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
35da0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
35db0 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
35dc0 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e  void *pArg,.  in
35dd0 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
35de0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
35df0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
35e00 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  d*).);.int sqlit
35e10 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
35e20 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ion_v2(.  sqlite
35e30 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
35e40 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
35e50 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
35e60 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28  id *pArg,.  int(
35e70 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
35e80 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
35e90 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
35ea0 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
35eb0 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69  roy)(void*).);.i
35ec0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
35ed0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20  e_collation16(. 
35ee0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
35ef0 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c  nst void *zName,
35f00 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
35f10 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a   .  void *pArg,.
35f20 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
35f30 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
35f40 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
35f50 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a   void*).);../*.*
35f60 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c  * CAPI3REF: Coll
35f70 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c  ation Needed Cal
35f80 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f  lbacks.**.** ^To
35f90 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f   avoid having to
35fa0 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f   register all co
35fb0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
35fc0 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62  s before a datab
35fd0 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ase.** can be us
35fe0 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c  ed, a single cal
35ff0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d  lback function m
36000 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64  ay be registered
36010 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61   with the.** [da
36020 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36030 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  n] to be invoked
36040 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64   whenever an und
36050 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
36060 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20  .** sequence is 
36070 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
36080 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
36090 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75   is registered u
360a0 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
360b0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
360c0 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e  d() API,.** then
360d0 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68   it is passed th
360e0 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66  e names of undef
360f0 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ined collation s
36100 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69  equences as stri
36110 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69  ngs.** encoded i
36120 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c  n UTF-8. ^If sql
36130 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
36140 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65  eeded16() is use
36150 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20  d,.** the names 
36160 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54  are passed as UT
36170 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20  F-16 in machine 
36180 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
36190 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  r..** ^A call to
361a0 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e   either function
361b0 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 65 78   replaces the ex
361c0 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e  isting collation
361d0 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b  -needed callback
361e0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74  ..**.** ^(When t
361f0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
36200 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73  nvoked, the firs
36210 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  t argument passe
36220 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f  d is a copy.** o
36230 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
36240 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
36250 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
36260 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  d() or.** sqlite
36270 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
36280 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63  ed16().  The sec
36290 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
362a0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
362b0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65  connection.  The
362c0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
362d0 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
362e0 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
362f0 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72  _UTF16BE],.** or
36300 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
36310 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ], indicating th
36320 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65  e most desirable
36330 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c   form of the col
36340 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
36350 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  ce function requ
36360 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74  ired.  The fourt
36370 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  h parameter is t
36380 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
36390 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61  * required colla
363a0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e  tion sequence.)^
363b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
363c0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ack function sho
363d0 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65  uld register the
363e0 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69   desired collati
363f0 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
36400 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
36410 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  ation()], [sqlit
36420 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
36430 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  ion16()], or.** 
36440 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
36450 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e  collation_v2()].
36460 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
36470 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
36480 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
36490 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28   void*, .  void(
364a0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
364b0 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
364c0 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69  onst char*).);.i
364d0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
364e0 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20  tion_needed16(. 
364f0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
36500 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76  id*,.  void(*)(v
36510 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
36520 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
36530 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64   void*).);..#ifd
36540 65 66 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f  ef SQLITE_HAS_CO
36550 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  DEC./*.** Specif
36560 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e  y the key for an
36570 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62   encrypted datab
36580 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69  ase.  This routi
36590 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  ne should be.** 
365a0 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74  called right aft
365b0 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  er sqlite3_open(
365c0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  )..**.** The cod
365d0 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  e to implement t
365e0 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61  his API is not a
365f0 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
36600 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a  public release.*
36610 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  * of SQLite..*/.
36620 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28  int sqlite3_key(
36630 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
36640 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36650 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
36660 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
36670 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
36680 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
36690 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b  /* The key */.);
366a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79  .int sqlite3_key
366b0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
366c0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
366d0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
366e0 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
366f0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
36700 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20  *zDbName,       
36710 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
36720 68 65 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  he database */. 
36730 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
36740 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
36750 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b  /* The key */.);
36760 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74  ../*.** Change t
36770 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65  he key on an ope
36780 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20  n database.  If 
36790 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61  the current data
367a0 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65  base is not.** e
367b0 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72  ncrypted, this r
367c0 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72  outine will encr
367d0 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77  ypt it.  If pNew
367e0 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20  ==0 or nNew==0, 
367f0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
36800 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a  is decrypted..**
36810 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
36820 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
36830 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
36840 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
36850 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
36860 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
36870 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20  qlite3_rekey(.  
36880 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
36890 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
368a0 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
368b0 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
368c0 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
368d0 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
368e0 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29  The new key */.)
368f0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  ;.int sqlite3_re
36900 6b 65 79 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  key_v2(.  sqlite
36910 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
36920 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
36930 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
36940 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  ed */.  const ch
36950 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20  ar *zDbName,    
36960 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
36970 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 2a  f the database *
36980 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
36990 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20  pKey, int nKey  
369a0 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65     /* The new ke
369b0 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53  y */.);../*.** S
369c0 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76  pecify the activ
369d0 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20  ation key for a 
369e0 53 45 45 20 64 61 74 61 62 61 73 65 2e 20 20 55  SEE database.  U
369f0 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61  nless .** activa
36a00 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65  ted, none of the
36a10 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69   SEE routines wi
36a20 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64  ll work..*/.void
36a30 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74   sqlite3_activat
36a40 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63  e_see(.  const c
36a50 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65  har *zPassPhrase
36a60 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76          /* Activ
36a70 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a  ation phrase */.
36a80 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65  );.#endif..#ifde
36a90 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f  f SQLITE_ENABLE_
36aa0 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63  CEROD./*.** Spec
36ab0 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69  ify the activati
36ac0 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52  on key for a CER
36ad0 4f 44 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e  OD database.  Un
36ae0 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74  less .** activat
36af0 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20  ed, none of the 
36b00 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77  CEROD routines w
36b10 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69  ill work..*/.voi
36b20 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61  d sqlite3_activa
36b30 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73  te_cerod(.  cons
36b40 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72  t char *zPassPhr
36b50 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63  ase        /* Ac
36b60 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20  tivation phrase 
36b70 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  */.);.#endif../*
36b80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75  .** CAPI3REF: Su
36b90 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20  spend Execution 
36ba0 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65  For A Short Time
36bb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
36bc0 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74  e3_sleep() funct
36bd0 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 63  ion causes the c
36be0 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f  urrent thread to
36bf0 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69   suspend executi
36c00 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61  on.** for at lea
36c10 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d  st a number of m
36c20 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63  illiseconds spec
36c30 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72  ified in its par
36c40 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  ameter..**.** If
36c50 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
36c60 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73  ystem does not s
36c70 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71  upport sleep req
36c80 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69  uests with.** mi
36c90 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72  llisecond time r
36ca0 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20  esolution, then 
36cb0 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65  the time will be
36cc0 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a   rounded up to.*
36cd0 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65  * the nearest se
36ce0 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72  cond. The number
36cf0 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
36d00 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c   of sleep actual
36d10 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  ly.** requested 
36d20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69  from the operati
36d30 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74  ng system is ret
36d40 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  urned..**.** ^SQ
36d50 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
36d60 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62  this interface b
36d70 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53  y calling the xS
36d80 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  leep().** method
36d90 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
36da0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
36db0 6a 65 63 74 2e 20 20 49 66 20 74 68 65 20 78 53  ject.  If the xS
36dc0 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a  leep() method.**
36dd0 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
36de0 56 46 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65  VFS is not imple
36df0 6d 65 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79  mented correctly
36e00 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  , or not impleme
36e10 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20  nted at.** all, 
36e20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
36e30 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65  r of sqlite3_sle
36e40 65 70 28 29 20 6d 61 79 20 64 65 76 69 61 74 65  ep() may deviate
36e50 20 66 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69   from the descri
36e60 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20  ption.** in the 
36e70 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
36e80 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  phs..*/.int sqli
36e90 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a  te3_sleep(int);.
36ea0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36eb0 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c   Name Of The Fol
36ec0 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70  der Holding Temp
36ed0 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a  orary Files.**.*
36ee0 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62  * ^(If this glob
36ef0 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d  al variable is m
36f00 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
36f10 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69  a string which i
36f20 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
36f30 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61   a folder (a.k.a
36f40 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68  . directory), th
36f50 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79  en all temporary
36f60 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65   files.** create
36f70 64 20 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e  d by SQLite when
36f80 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69   using a built-i
36f90 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  n [sqlite3_vfs |
36fa0 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65   VFS].** will be
36fb0 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20   placed in that 
36fc0 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49  directory.)^  ^I
36fd0 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  f this variable.
36fe0 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
36ff0 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
37000 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61  e performs a sea
37010 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f  rch for an appro
37020 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72  priate.** tempor
37030 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f  ary file directo
37040 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ry..**.** It is 
37050 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64  not safe to read
37060 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
37070 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65  variable in more
37080 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72   than one.** thr
37090 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20  ead at a time.  
370a0 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
370b0 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79  o read or modify
370c0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a   this variable.*
370d0 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 65  * if a [database
370e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
370f0 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 68  being used at th
37100 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61  e same time in a
37110 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72   separate.** thr
37120 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e  ead..** It is in
37130 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73  tended that this
37140 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74   variable be set
37150 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74   once.** as part
37160 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74   of process init
37170 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62  ialization and b
37180 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65  efore any SQLite
37190 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f   interface.** ro
371a0 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e  utines have been
371b0 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74   called and that
371c0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 72   this variable r
371d0 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a  emain unchanged.
371e0 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a  ** thereafter..*
371f0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f  *.** ^The [temp_
37200 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
37210 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69  pragma] may modi
37220 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
37230 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74   and cause.** it
37240 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d   to point to mem
37250 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
37260 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
37270 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72  c].  ^Furthermor
37280 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f  e,.** the [temp_
37290 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
372a0 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61  pragma] always a
372b0 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20  ssumes that any 
372c0 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74  string.** that t
372d0 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69  his variable poi
372e0 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69  nts to is held i
372f0 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  n memory obtaine
37300 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69  d from .** [sqli
37310 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20  te3_malloc] and 
37320 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61  the pragma may a
37330 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74  ttempt to free t
37340 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73  hat memory.** us
37350 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
37360 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66  e]..** Hence, if
37370 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69   this variable i
37380 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63  s modified direc
37390 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73  tly, either it s
373a0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65  hould be.** made
373b0 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f   NULL or made to
373c0 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79   point to memory
373d0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
373e0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a  sqlite3_malloc].
373f0 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75  ** or else the u
37400 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f  se of the [temp_
37410 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
37420 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62  pragma] should b
37430 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 0a 2a 2a  e avoided..**.**
37440 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
37450 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72  ows Runtime user
37460 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70  s:</b>  The temp
37470 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20  orary directory 
37480 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70  must be set.** p
37490 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20  rior to calling 
374a0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5d 20 6f  [sqlite3_open] o
374b0 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
374c0 76 32 5d 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  v2].  Otherwise,
374d0 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74   various.** feat
374e0 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72  ures that requir
374f0 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d  e the use of tem
37500 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79  porary files may
37510 20 66 61 69 6c 2e 20 20 48 65 72 65 20 69 73 20   fail.  Here is 
37520 61 6e 0a 2a 2a 20 65 78 61 6d 70 6c 65 20 6f 66  an.** example of
37530 20 68 6f 77 20 74 6f 20 64 6f 20 74 68 69 73 20   how to do this 
37540 75 73 69 6e 67 20 43 2b 2b 20 77 69 74 68 20 74  using C++ with t
37550 68 65 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69  he Windows Runti
37560 6d 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  me:.**.** <block
37570 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 4c  quote><pre>.** L
37580 50 43 57 53 54 52 20 7a 50 61 74 68 20 3d 20 57  PCWSTR zPath = W
37590 69 6e 64 6f 77 73 3a 3a 53 74 6f 72 61 67 65 3a  indows::Storage:
375a0 3a 41 70 70 6c 69 63 61 74 69 6f 6e 44 61 74 61  :ApplicationData
375b0 3a 3a 43 75 72 72 65 6e 74 2d 3e 0a 2a 2a 20 26  ::Current->.** &
375c0 6e 62 73 70 3b 20 20 20 20 20 54 65 6d 70 6f 72  nbsp;     Tempor
375d0 61 72 79 46 6f 6c 64 65 72 2d 3e 50 61 74 68 2d  aryFolder->Path-
375e0 3e 44 61 74 61 28 29 3b 0a 2a 2a 20 63 68 61 72  >Data();.** char
375f0 20 7a 50 61 74 68 42 75 66 26 23 39 31 3b 4d 41   zPathBuf&#91;MA
37600 58 5f 50 41 54 48 20 2b 20 31 26 23 39 33 3b 3b  X_PATH + 1&#93;;
37610 0a 2a 2a 20 6d 65 6d 73 65 74 28 7a 50 61 74 68  .** memset(zPath
37620 42 75 66 2c 20 30 2c 20 73 69 7a 65 6f 66 28 7a  Buf, 0, sizeof(z
37630 50 61 74 68 42 75 66 29 29 3b 0a 2a 2a 20 57 69  PathBuf));.** Wi
37640 64 65 43 68 61 72 54 6f 4d 75 6c 74 69 42 79 74  deCharToMultiByt
37650 65 28 43 50 5f 55 54 46 38 2c 20 30 2c 20 7a 50  e(CP_UTF8, 0, zP
37660 61 74 68 2c 20 2d 31 2c 20 7a 50 61 74 68 42 75  ath, -1, zPathBu
37670 66 2c 20 73 69 7a 65 6f 66 28 7a 50 61 74 68 42  f, sizeof(zPathB
37680 75 66 29 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20  uf),.** &nbsp;  
37690 20 20 20 4e 55 4c 4c 2c 20 4e 55 4c 4c 29 3b 0a     NULL, NULL);.
376a0 2a 2a 20 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  ** sqlite3_temp_
376b0 64 69 72 65 63 74 6f 72 79 20 3d 20 73 71 6c 69  directory = sqli
376c0 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 25 73 22  te3_mprintf("%s"
376d0 2c 20 7a 50 61 74 68 42 75 66 29 3b 0a 2a 2a 20  , zPathBuf);.** 
376e0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
376f0 74 65 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  te>.*/.SQLITE_EX
37700 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74  TERN char *sqlit
37710 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
37720 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  y;../*.** CAPI3R
37730 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20  EF: Name Of The 
37740 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 44  Folder Holding D
37750 61 74 61 62 61 73 65 20 46 69 6c 65 73 0a 2a 2a  atabase Files.**
37760 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c  .** ^(If this gl
37770 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73  obal variable is
37780 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
37790 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  o a string which
377a0 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20   is.** the name 
377b0 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b  of a folder (a.k
377c0 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20  .a. directory), 
377d0 74 68 65 6e 20 61 6c 6c 20 64 61 74 61 62 61 73  then all databas
377e0 65 20 66 69 6c 65 73 0a 2a 2a 20 73 70 65 63 69  e files.** speci
377f0 66 69 65 64 20 77 69 74 68 20 61 20 72 65 6c 61  fied with a rela
37800 74 69 76 65 20 70 61 74 68 6e 61 6d 65 20 61 6e  tive pathname an
37810 64 20 63 72 65 61 74 65 64 20 6f 72 20 61 63 63  d created or acc
37820 65 73 73 65 64 20 62 79 0a 2a 2a 20 53 51 4c 69  essed by.** SQLi
37830 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20  te when using a 
37840 62 75 69 6c 74 2d 69 6e 20 77 69 6e 64 6f 77 73  built-in windows
37850 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
37860 56 46 53 5d 20 77 69 6c 6c 20 62 65 20 61 73 73  VFS] will be ass
37870 75 6d 65 64 0a 2a 2a 20 74 6f 20 62 65 20 72 65  umed.** to be re
37880 6c 61 74 69 76 65 20 74 6f 20 74 68 61 74 20 64  lative to that d
37890 69 72 65 63 74 6f 72 79 2e 29 5e 20 5e 49 66 20  irectory.)^ ^If 
378a0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73  this variable is
378b0 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
378c0 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
378d0 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6c 6c  assumes that all
378e0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20   database files 
378f0 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 77 69 74  specified.** wit
37900 68 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74  h a relative pat
37910 68 6e 61 6d 65 20 61 72 65 20 72 65 6c 61 74 69  hname are relati
37920 76 65 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  ve to the curren
37930 74 20 64 69 72 65 63 74 6f 72 79 0a 2a 2a 20 66  t directory.** f
37940 6f 72 20 74 68 65 20 70 72 6f 63 65 73 73 2e 20  or the process. 
37950 20 4f 6e 6c 79 20 74 68 65 20 77 69 6e 64 6f 77   Only the window
37960 73 20 56 46 53 20 6d 61 6b 65 73 20 75 73 65 20  s VFS makes use 
37970 6f 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 0a 2a  of this global.*
37980 2a 20 76 61 72 69 61 62 6c 65 3b 20 69 74 20 69  * variable; it i
37990 73 20 69 67 6e 6f 72 65 64 20 62 79 20 74 68 65  s ignored by the
379a0 20 75 6e 69 78 20 56 46 53 2e 0a 2a 2a 0a 2a 2a   unix VFS..**.**
379b0 20 43 68 61 6e 67 69 6e 67 20 74 68 65 20 76 61   Changing the va
379c0 6c 75 65 20 6f 66 20 74 68 69 73 20 76 61 72 69  lue of this vari
379d0 61 62 6c 65 20 77 68 69 6c 65 20 61 20 64 61 74  able while a dat
379e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
379f0 20 69 73 0a 2a 2a 20 6f 70 65 6e 20 63 61 6e 20   is.** open can 
37a00 72 65 73 75 6c 74 20 69 6e 20 61 20 63 6f 72 72  result in a corr
37a10 75 70 74 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a  upt database..**
37a20 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
37a30 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f  fe to read or mo
37a40 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
37a50 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20  le in more than 
37a60 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74  one.** thread at
37a70 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20   a time.  It is 
37a80 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64  not safe to read
37a90 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
37aa0 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61  variable.** if a
37ab0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
37ac0 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
37ad0 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65  used at the same
37ae0 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72   time in a separ
37af0 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a  ate.** thread..*
37b00 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64  * It is intended
37b10 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
37b20 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a  ble be set once.
37b30 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72  ** as part of pr
37b40 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
37b50 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20  tion and before 
37b60 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
37b70 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  face.** routines
37b80 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
37b90 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  d and that this 
37ba0 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20  variable remain 
37bb0 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65  unchanged.** the
37bc0 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  reafter..**.** ^
37bd0 54 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f  The [data_store_
37be0 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
37bf0 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69  ] may modify thi
37c00 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63  s variable and c
37c10 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f  ause.** it to po
37c20 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  int to memory ob
37c30 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
37c40 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e  ite3_malloc].  ^
37c50 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20  Furthermore,.** 
37c60 74 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f  the [data_store_
37c70 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
37c80 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73  ] always assumes
37c90 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67   that any string
37ca0 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61  .** that this va
37cb0 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f  riable points to
37cc0 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f   is held in memo
37cd0 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
37ce0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
37cf0 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72  lloc] and the pr
37d00 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74  agma may attempt
37d10 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65   to free that me
37d20 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  mory.** using [s
37d30 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a  qlite3_free]..**
37d40 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20   Hence, if this 
37d50 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69  variable is modi
37d60 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65  fied directly, e
37d70 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20  ither it should 
37d80 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20  be.** made NULL 
37d90 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  or made to point
37da0 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   to memory obtai
37db0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
37dc0 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20  3_malloc].** or 
37dd0 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 20  else the use of 
37de0 74 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f  the [data_store_
37df0 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
37e00 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69  ] should be avoi
37e10 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ded..*/.SQLITE_E
37e20 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69  XTERN char *sqli
37e30 74 65 33 5f 64 61 74 61 5f 64 69 72 65 63 74 6f  te3_data_directo
37e40 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ry;../*.** CAPI3
37e50 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75  REF: Test For Au
37e60 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a  to-Commit Mode.*
37e70 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74  * KEYWORDS: {aut
37e80 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a  ocommit mode}.**
37e90 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
37ea0 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28  _get_autocommit(
37eb0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
37ec0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a  rns non-zero or.
37ed0 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67  ** zero if the g
37ee0 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f  iven database co
37ef0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69  nnection is or i
37f00 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d  s not in autocom
37f10 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73  mit mode,.** res
37f20 70 65 63 74 69 76 65 6c 79 2e 20 20 5e 41 75 74  pectively.  ^Aut
37f30 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
37f40 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  on by default..*
37f50 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  * ^Autocommit mo
37f60 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  de is disabled b
37f70 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74  y a [BEGIN] stat
37f80 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63  ement..** ^Autoc
37f90 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65  ommit mode is re
37fa0 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43  -enabled by a [C
37fb0 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42  OMMIT] or [ROLLB
37fc0 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63  ACK]..**.** If c
37fd0 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20  ertain kinds of 
37fe0 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20  errors occur on 
37ff0 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  a statement with
38000 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65  in a multi-state
38010 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74  ment.** transact
38020 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c  ion (errors incl
38030 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55  uding [SQLITE_FU
38040 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45  LL], [SQLITE_IOE
38050 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  RR],.** [SQLITE_
38060 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f  NOMEM], [SQLITE_
38070 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  BUSY], and [SQLI
38080 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74  TE_INTERRUPT]) t
38090 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73  hen the.** trans
380a0 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20  action might be 
380b0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
380c0 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20  matically.  The 
380d0 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66  only way to.** f
380e0 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72 20  ind out whether 
380f0 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
38100 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
38110 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
38120 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72   after.** an err
38130 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 69  or is to use thi
38140 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  s function..**.*
38150 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72  * If another thr
38160 65 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20  ead changes the 
38170 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75  autocommit statu
38180 73 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  s of the databas
38190 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
381a0 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69  while this routi
381b0 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74  ne is running, t
381c0 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
381d0 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66  alue.** is undef
381e0 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ined..*/.int sql
381f0 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d  ite3_get_autocom
38200 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  mit(sqlite3*);..
38210 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
38220 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61 73  Find The Databas
38230 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72  e Handle Of A Pr
38240 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
38250 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
38260 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e  te3_db_handle in
38270 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
38280 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
38290 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
382a0 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b  .** to which a [
382b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
382c0 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 5e 54  nt] belongs.  ^T
382d0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
382e0 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75  nection].** retu
382f0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
38300 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 68 65  db_handle is the
38310 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
38320 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74  connection].** t
38330 68 61 74 20 77 61 73 20 74 68 65 20 66 69 72 73  hat was the firs
38340 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  t argument.** to
38350 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
38360 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c  epare_v2()] call
38370 20 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74   (or its variant
38380 73 29 20 74 68 61 74 20 77 61 73 20 75 73 65 64  s) that was used
38390 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68   to.** create th
383a0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  e statement in t
383b0 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a  he first place..
383c0 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
383d0 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  te3_db_handle(sq
383e0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
383f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
38400 65 74 75 72 6e 20 54 68 65 20 46 69 6c 65 6e 61  eturn The Filena
38410 6d 65 20 46 6f 72 20 41 20 44 61 74 61 62 61 73  me For A Databas
38420 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a  e Connection.**.
38430 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
38440 64 62 5f 66 69 6c 65 6e 61 6d 65 28 44 2c 4e 29  db_filename(D,N)
38450 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
38460 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
38470 61 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 61 73  a filename.** as
38480 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 64 61  sociated with da
38490 74 61 62 61 73 65 20 4e 20 6f 66 20 63 6f 6e 6e  tabase N of conn
384a0 65 63 74 69 6f 6e 20 44 2e 20 20 5e 54 68 65 20  ection D.  ^The 
384b0 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69  main database fi
384c0 6c 65 0a 2a 2a 20 68 61 73 20 74 68 65 20 6e 61  le.** has the na
384d0 6d 65 20 22 6d 61 69 6e 22 2e 20 20 49 66 20 74  me "main".  If t
384e0 68 65 72 65 20 69 73 20 6e 6f 20 61 74 74 61 63  here is no attac
384f0 68 65 64 20 64 61 74 61 62 61 73 65 20 4e 20 6f  hed database N o
38500 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  n the database.*
38510 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20  * connection D, 
38520 6f 72 20 69 66 20 64 61 74 61 62 61 73 65 20 4e  or if database N
38530 20 69 73 20 61 20 74 65 6d 70 6f 72 61 72 79 20   is a temporary 
38540 6f 72 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  or in-memory dat
38550 61 62 61 73 65 2c 20 74 68 65 6e 0a 2a 2a 20 61  abase, then.** a
38560 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
38570 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
38580 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 72   ^The filename r
38590 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
385a0 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 20  function is the 
385b0 6f 75 74 70 75 74 20 6f 66 20 74 68 65 0a 2a 2a  output of the.**
385c0 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 20 6d   xFullPathname m
385d0 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 56 46  ethod of the [VF
385e0 53 5d 2e 20 20 5e 49 6e 20 6f 74 68 65 72 20 77  S].  ^In other w
385f0 6f 72 64 73 2c 20 74 68 65 20 66 69 6c 65 6e 61  ords, the filena
38600 6d 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 61 6e  me.** will be an
38610 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 6e 61   absolute pathna
38620 6d 65 2c 20 65 76 65 6e 20 69 66 20 74 68 65 20  me, even if the 
38630 66 69 6c 65 6e 61 6d 65 20 75 73 65 64 0a 2a 2a  filename used.**
38640 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74   to open the dat
38650 61 62 61 73 65 20 6f 72 69 67 69 6e 61 6c 6c 79  abase originally
38660 20 77 61 73 20 61 20 55 52 49 20 6f 72 20 72 65   was a URI or re
38670 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d 65 2e  lative pathname.
38680 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
38690 73 71 6c 69 74 65 33 5f 64 62 5f 66 69 6c 65 6e  sqlite3_db_filen
386a0 61 6d 65 28 73 71 6c 69 74 65 33 20 2a 64 62 2c  ame(sqlite3 *db,
386b0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
386c0 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Name);../*.** CA
386d0 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
386e0 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20  e if a database 
386f0 69 73 20 72 65 61 64 2d 6f 6e 6c 79 0a 2a 2a 0a  is read-only.**.
38700 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
38710 64 62 5f 72 65 61 64 6f 6e 6c 79 28 44 2c 4e 29  db_readonly(D,N)
38720 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
38730 6e 73 20 31 20 69 66 20 74 68 65 20 64 61 74 61  ns 1 if the data
38740 62 61 73 65 20 4e 0a 2a 2a 20 6f 66 20 63 6f 6e  base N.** of con
38750 6e 65 63 74 69 6f 6e 20 44 20 69 73 20 72 65 61  nection D is rea
38760 64 2d 6f 6e 6c 79 2c 20 30 20 69 66 20 69 74 20  d-only, 0 if it 
38770 69 73 20 72 65 61 64 2f 77 72 69 74 65 2c 20 6f  is read/write, o
38780 72 20 2d 31 20 69 66 20 4e 20 69 73 20 6e 6f 74  r -1 if N is not
38790 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
387a0 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20 63 6f  a database on co
387b0 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2f 0a 69  nnection D..*/.i
387c0 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 72 65  nt sqlite3_db_re
387d0 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 20 2a  adonly(sqlite3 *
387e0 64 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  db, const char *
387f0 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a  zDbName);../*.**
38800 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20   CAPI3REF: Find 
38810 74 68 65 20 6e 65 78 74 20 70 72 65 70 61 72 65  the next prepare
38820 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  d statement.**.*
38830 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63  * ^This interfac
38840 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
38850 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20  ter to the next 
38860 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
38870 65 6e 74 5d 20 61 66 74 65 72 0a