/ Hex Artifact Content
Login

Artifact 49398dec1abb0a2caecff17da6202179ca487fe8:


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 6d 75 74 65 78 69 6e 67 20 63 6f  iled mutexing co
1be0: 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74  de omitted due t
1bf0: 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  o the.** [SQLITE
1c00: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d  _THREADSAFE] com
1c10: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
1c20: 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e   being set to 0.
1c30: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61  .**.** SQLite ca
1c40: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69  n be compiled wi
1c50: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75  th or without mu
1c60: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20  texes.  When.** 
1c70: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
1c80: 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f  ADSAFE] C prepro
1c90: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20  cessor macro is 
1ca0: 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a  1 or 2, mutexes.
1cb0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61  ** are enabled a
1cc0: 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72  nd SQLite is thr
1cd0: 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74  eadsafe.  When t
1ce0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  he.** [SQLITE_TH
1cf0: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20  READSAFE] macro 
1d00: 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75  is 0, .** the mu
1d10: 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65  texes are omitte
1d20: 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20  d.  Without the 
1d30: 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e  mutexes, it is n
1d40: 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73  ot safe.** to us
1d50: 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72  e SQLite concurr
1d60: 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20  ently from more 
1d70: 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e  than one thread.
1d80: 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20  .**.** Enabling 
1d90: 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61  mutexes incurs a
1da0: 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66   measurable perf
1db0: 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e  ormance penalty.
1dc0: 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20  .** So if speed 
1dd0: 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70  is of utmost imp
1de0: 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65  ortance, it make
1df0: 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62  s sense to disab
1e00: 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  le.** the mutexe
1e10: 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69  s.  But for maxi
1e20: 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65  mum safety, mute
1e30: 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e  xes should be en
1e40: 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  abled..** ^The d
1e50: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
1e60: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
1e70: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
1e80: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
1e90: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
1ea0: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  y an application
1eb0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
1ec0: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f  at the.** versio
1ed0: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74  n of SQLite that
1ee0: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61   it is linking a
1ef0: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69  gainst was compi
1f00: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
1f10: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20  desired setting 
1f20: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
1f30: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
1f40: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
1f50: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f  erface only repo
1f60: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  rts on the compi
1f70: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65  le-time mutex se
1f80: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20  tting.** of the 
1f90: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1fa0: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51  FE] flag.  If SQ
1fb0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
1fc0: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f   with.** SQLITE_
1fd0: 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20  THREADSAFE=1 or 
1fe0: 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20  =2 then mutexes 
1ff0: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
2000: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61  efault but.** ca
2010: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61  n be fully or pa
2020: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  rtially disabled
2030: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f   using a call to
2040: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
2050: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ()].** with the 
2060: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f  verbs [SQLITE_CO
2070: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
2080: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  D], [SQLITE_CONF
2090: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c  IG_MULTITHREAD],
20a0: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  .** or [SQLITE_C
20b0: 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e  ONFIG_MUTEX].  ^
20c0: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  (The return valu
20d0: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69  e of the.** sqli
20e0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
20f0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20   function shows 
2100: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65  only the compile
2110: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66  -time setting of
2120: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74  .** thread safet
2130: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74  y, not any run-t
2140: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ime changes to t
2150: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65  hat setting made
2160: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   by.** sqlite3_c
2170: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65  onfig(). In othe
2180: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74  r words, the ret
2190: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
21a0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
21b0: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e  e().** is unchan
21c0: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ged by calls to 
21d0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
21e0: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68  .)^.**.** See th
21f0: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
2200: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
2210: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
2220: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
2230: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
2240: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
2250: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2260: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2270: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
2280: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
2290: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
22a0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
22c0: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
22d0: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
22e0: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
22f0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
2300: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
2310: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
2320: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
2330: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
2340: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
2350: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
2360: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
2370: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2380: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2390: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
23a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
23b0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
23c0: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
23d0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
23e0: 73 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20  se()].** is its 
23f0: 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65  destructor.  The
2400: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2410: 72 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75  r interfaces (su
2420: 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65  ch as.** [sqlite
2430: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
2440: 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2450: 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e  _function()], an
2460: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  d.** [sqlite3_bu
2470: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f  sy_timeout()] to
2480: 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29   name but three)
2490: 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64   that are method
24a0: 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  s on an.** sqlit
24b0: 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79  e3 object..*/.ty
24c0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
24d0: 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f  ite3 sqlite3;../
24e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36  *.** CAPI3REF: 6
24f0: 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79  4-Bit Integer Ty
2500: 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
2510: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
2520: 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a  lite_uint64.**.*
2530: 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20  * Because there 
2540: 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74  is no cross-plat
2550: 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63  form way to spec
2560: 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67  ify 64-bit integ
2570: 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69  er types.** SQLi
2580: 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65  te includes type
2590: 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20  defs for 64-bit 
25a0: 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67  signed and unsig
25b0: 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a  ned integers..**
25c0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
25d0: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
25e0: 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65  3_uint64 are the
25f0: 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20   preferred type 
2600: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20  definitions..** 
2610: 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  The sqlite_int64
2620: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2630: 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70  64 types are sup
2640: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77  ported for backw
2650: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ards.** compatib
2660: 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  ility only..**.*
2670: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
2680: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
2690: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
26a0: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
26b0: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
26c0: 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  -922337203685477
26d0: 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37  5808 and +922337
26e0: 32 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e  2036854775807 in
26f0: 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a  clusive.  ^The.*
2700: 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  * sqlite3_uint64
2710: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2720: 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f  64 types can sto
2730: 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  re integer value
2740: 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20  s .** between 0 
2750: 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33  and +18446744073
2760: 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73  709551615 inclus
2770: 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  ive..*/.#ifdef S
2780: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
2790: 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54  .  typedef SQLIT
27a0: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  E_INT64_TYPE sql
27b0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
27c0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51  edef unsigned SQ
27d0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27e0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
27f0: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53  elif defined(_MS
2800: 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65  C_VER) || define
2810: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a  d(__BORLANDC__).
2820: 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36    typedef __int6
2830: 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  4 sqlite_int64;.
2840: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2850: 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74  ed __int64 sqlit
2860: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a  e_uint64;.#else.
2870: 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c    typedef long l
2880: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69  ong int sqlite_i
2890: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
28a0: 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f  unsigned long lo
28b0: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69  ng int sqlite_ui
28c0: 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70  nt64;.#endif.typ
28d0: 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36  edef sqlite_int6
28e0: 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b  4 sqlite3_int64;
28f0: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
2900: 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  uint64 sqlite3_u
2910: 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66  int64;../*.** If
2920: 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61   compiling for a
2930: 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20   processor that 
2940: 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70  lacks floating p
2950: 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a  oint support,.**
2960: 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65   substitute inte
2970: 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67  ger for floating
2980: 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65  -point..*/.#ifde
2990: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c  f SQLITE_OMIT_FL
29a0: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64  OATING_POINT.# d
29b0: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c  efine double sql
29c0: 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69  ite3_int64.#endi
29d0: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
29e0: 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74  F: Closing A Dat
29f0: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
2a00: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a10: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74  te3_close() rout
2a20: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72  ine is the destr
2a30: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73  uctor for the [s
2a40: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a  qlite3] object..
2a50: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
2a60: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74  ite3_close() ret
2a70: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
2a80: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2a90: 62 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63  bject is.** succ
2aa0: 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79  essfully destroy
2ab0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
2ac0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20  iated resources 
2ad0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ae0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2af0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65  ons must [sqlite
2b00: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2b10: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2b20: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2b30: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2b40: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2b50: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
2b60: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
2b70: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
2b80: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2b90: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
2ba0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
2bb0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
2bc0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2bd0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20   is called on a 
2be0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2bf0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c  tion] that still
2c00: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64   has.** outstand
2c10: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74  ing [prepared st
2c20: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c  atements] or [BL
2c30: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65  OB handles], the
2c40: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  n it returns.** 
2c50: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a  SQLITE_BUSY..**.
2c60: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f  ** ^If [sqlite3_
2c70: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
2c80: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
2c90: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
2ca0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
2cb0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
2cc0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2cd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
2ce0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2cf0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75  te3_close(C)] mu
2d00: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
2d10: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
2d20: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2d30: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2d40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
2d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2d60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2d70: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2d80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2d90: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
2da0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
2db0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
2dc0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55  lose() with a NU
2dd0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  LL pointer argum
2de0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72  ent is a .** har
2df0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
2e00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
2e10: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f  e(sqlite3 *);../
2e20: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
2e30: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
2e40: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
2e50: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
2e60: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
2e70: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
2e80: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
2e90: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
2ea0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
2eb0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
2ec0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
2ed0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2ee0: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
2ef0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2f00: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
2f10: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
2f20: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
2f30: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
2f40: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
2f50: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
2f60: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
2f70: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2f80: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f90: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
2fa0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
2fb0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
2fc0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
2fd0: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
2fe0: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
2ff0: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3000: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3010: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3020: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3030: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
3040: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
3050: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
3060: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
3070: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3080: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
3090: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
30a0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
30b0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
30c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
30d0: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
30e0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
30f0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3100: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3110: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3120: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3130: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
3140: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
3150: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
3160: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
3170: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
3180: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
3190: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
31a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
31b0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
31c0: 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67  s relayed throug
31d0: 68 20 74 6f 20 74 68 65 20 31 73 74 20 61 72 67  h to the 1st arg
31e0: 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a  ument of each.**
31f0: 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61   callback invoca
3200: 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63  tion.  ^If the c
3210: 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20  allback pointer 
3220: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3230: 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ).** is NULL, th
3240: 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69  en no callback i
3250: 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61  s ever invoked a
3260: 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61  nd result rows a
3270: 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a  re.** ignored..*
3280: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f  *.** ^If an erro
3290: 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65  r occurs while e
32a0: 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51  valuating the SQ
32b0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73  L statements pas
32c0: 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69  sed into.** sqli
32d0: 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e  te3_exec(), then
32e0: 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
32f0: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d  e current statem
3300: 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a  ent stops and.**
3310: 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 61 74   subsequent stat
3320: 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70  ements are skipp
3330: 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68  ed.  ^If the 5th
3340: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3350: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
3360: 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
3370: 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61   any error messa
3380: 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  ge is written in
3390: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
33a0: 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
33b0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
33c0: 64 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 68  d passed back th
33d0: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
33e0: 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61  rameter..** To a
33f0: 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b  void memory leak
3400: 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  s, the applicati
3410: 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65  on should invoke
3420: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
3430: 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65  ].** on error me
3440: 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 72 65  ssage strings re
3450: 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74  turned through t
3460: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
3470: 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65   of.** of sqlite
3480: 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20 74  3_exec() after t
3490: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
34a0: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f   string is no lo
34b0: 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20  nger needed..** 
34c0: 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61  ^If the 5th para
34d0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
34e0: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
34f0: 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72  ULL and no error
3500: 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e  s.** occur, then
3510: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3520: 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72  sets the pointer
3530: 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72 61   in its 5th para
3540: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c  meter to.** NULL
3550: 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
3560: 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  g..**.** ^If an 
3570: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3580: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
3590: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71  non-zero, the sq
35a0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
35b0: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
35c0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74  SQLITE_ABORT wit
35d0: 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  hout invoking th
35e0: 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e  e callback again
35f0: 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20   and.** without 
3600: 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73  running any subs
3610: 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65  equent SQL state
3620: 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
3630: 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  e 2nd argument t
3640: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78  o the sqlite3_ex
3650: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75  ec() callback fu
3660: 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a  nction is the.**
3670: 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
3680: 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
3690: 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67 75  .  ^The 3rd argu
36a0: 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
36b0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61  te3_exec().** ca
36c0: 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72  llback is an arr
36d0: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
36e0: 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e  o strings obtain
36f0: 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a  ed as if from.**
3700: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
3710: 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f  _text()], one fo
3720: 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20  r each column.  
3730: 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f  ^If an element o
3740: 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  f a.** result ro
3750: 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74  w is NULL then t
3760: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
3770: 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
3780: 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74  for the.** sqlit
3790: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
37a0: 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ck is a NULL poi
37b0: 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20  nter.  ^The 4th 
37c0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a  argument to the.
37d0: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
37e0: 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  ) callback is an
37f0: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
3800: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68  rs to strings wh
3810: 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72  ere each.** entr
3820: 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68 65  y represents the
3830: 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70   name of corresp
3840: 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f  onding result co
3850: 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64  lumn as obtained
3860: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3870: 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d  3_column_name()]
3880: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
3890: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
38a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
38b0: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
38c0: 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  r, a pointer.** 
38d0: 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  to an empty stri
38e0: 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72  ng, or a pointer
38f0: 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f   that contains o
3900: 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 61  nly whitespace a
3910: 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f  nd/or .** SQL co
3920: 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20  mments, then no 
3930: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
3940: 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64  re evaluated and
3950: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
3960: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e   is not changed.
3970: 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69  .**.** Restricti
3980: 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ons:.**.** <ul>.
3990: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
39a0: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73  ication must ins
39b0: 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73 74  ure that the 1st
39c0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
39d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
39e0: 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64 20       is a valid 
39f0: 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  and open [databa
3a00: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
3a10: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3a20: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
3a30: 20 63 6c 6f 73 65 20 5b 64 61 74 61 62 61 73 65   close [database
3a40: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
3a50: 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20  cified by.**    
3a60: 20 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65    the 1st parame
3a70: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3a80: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69  xec() while sqli
3a90: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75  te3_exec() is ru
3aa0: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  nning..** <li> T
3ab0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3ac0: 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74  ust not modify t
3ad0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
3ae0: 20 74 65 78 74 20 70 61 73 73 65 64 20 69 6e 74   text passed int
3af0: 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e  o.**      the 2n
3b00: 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
3b10: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68  qlite3_exec() wh
3b20: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  ile sqlite3_exec
3b30: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  () is running..*
3b40: 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74 20 73  * </ul>.*/.int s
3b50: 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73  qlite3_exec(.  s
3b60: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20  qlite3*,        
3b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b80: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
3b90: 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
3ba0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  .  const char *s
3bb0: 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  ql,             
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
3bd0: 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
3be0: 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  ated */.  int (*
3bf0: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
3c00: 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a  int,char**,char*
3c10: 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b  *),  /* Callback
3c20: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
3c30: 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20  oid *,          
3c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c50: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74            /* 1st
3c60: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
3c70: 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20  lback */.  char 
3c80: 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20  **errmsg        
3c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ca0: 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
3cb0: 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
3cc0: 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
3cd0: 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f  I3REF: Result Co
3ce0: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
3cf0: 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f   SQLITE_OK {erro
3d00: 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63  r code} {error c
3d10: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  odes}.** KEYWORD
3d20: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d  S: {result code}
3d30: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a   {result codes}.
3d40: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
3d50: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
3d60: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
3d70: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
3d80: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
3d90: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  here in order to
3da0: 20 69 6e 64 69 63 61 74 65 20 73 75 63 63 65 73   indicate succes
3db0: 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  s or failure..**
3dc0: 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f  .** New error co
3dd0: 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  des may be added
3de0: 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
3df0: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
3e00: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
3e10: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
3e20: 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73  D | extended res
3e30: 75 6c 74 20 63 6f 64 65 73 5d 2c 0a 2a 2a 20 5b  ult codes],.** [
3e40: 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f  sqlite3_vtab_on_
3e50: 63 6f 6e 66 6c 69 63 74 28 29 5d 20 5b 53 51 4c  conflict()] [SQL
3e60: 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72  ITE_ROLLBACK | r
3e70: 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 0a 2a 2f  esult codes]..*/
3e80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3e90: 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 20  OK           0  
3ea0: 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72   /* Successful r
3eb0: 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69  esult */./* begi
3ec0: 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63  nning-of-error-c
3ed0: 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20  odes */.#define 
3ee0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20  SQLITE_ERROR    
3ef0: 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65      1   /* SQL e
3f00: 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20  rror or missing 
3f10: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
3f20: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
3f30: 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49  NAL     2   /* I
3f40: 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72  nternal logic er
3f50: 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f  ror in SQLite */
3f60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3f70: 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 20  PERM         3  
3f80: 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69   /* Access permi
3f90: 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ssion denied */.
3fa0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
3fb0: 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 20  BORT        4   
3fc0: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74  /* Callback rout
3fd0: 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 6e  ine requested an
3fe0: 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e   abort */.#defin
3ff0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20  e SQLITE_BUSY   
4000: 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65        5   /* The
4010: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
4020: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4030: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
4040: 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41  D       6   /* A
4050: 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61   table in the da
4060: 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64  tabase is locked
4070: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4080: 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  TE_NOMEM        
4090: 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28  7   /* A malloc(
40a0: 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66  ) failed */.#def
40b0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
40c0: 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41  NLY     8   /* A
40d0: 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20  ttempt to write 
40e0: 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62  a readonly datab
40f0: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
4100: 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20  QLITE_INTERRUPT 
4110: 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74     9   /* Operat
4120: 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62  ion terminated b
4130: 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  y sqlite3_interr
4140: 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20  upt()*/.#define 
4150: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20  SQLITE_IOERR    
4160: 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20     10   /* Some 
4170: 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f  kind of disk I/O
4180: 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20   error occurred 
4190: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
41a0: 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 31  E_CORRUPT     11
41b0: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
41c0: 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73  se disk image is
41d0: 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64   malformed */.#d
41e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
41f0: 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a  FOUND    12   /*
4200: 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20   Unknown opcode 
4210: 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  in sqlite3_file_
4220: 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65  control() */.#de
4230: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c  fine SQLITE_FULL
4240: 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20          13   /* 
4250: 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64  Insertion failed
4260: 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73   because databas
4270: 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65  e is full */.#de
4280: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
4290: 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20  OPEN    14   /* 
42a0: 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74  Unable to open t
42b0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
42c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
42d0: 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31  TE_PROTOCOL    1
42e0: 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  5   /* Database 
42f0: 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72  lock protocol er
4300: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
4310: 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20  QLITE_EMPTY     
4320: 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61    16   /* Databa
4330: 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23  se is empty */.#
4340: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43  define SQLITE_SC
4350: 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f  HEMA      17   /
4360: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73  * The database s
4370: 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f  chema changed */
4380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4390: 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20  TOOBIG      18  
43a0: 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c   /* String or BL
43b0: 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20  OB exceeds size 
43c0: 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65  limit */.#define
43d0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
43e0: 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72  NT  19   /* Abor
43f0: 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61  t due to constra
4400: 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f  int violation */
4410: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4420: 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20  MISMATCH    20  
4430: 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69   /* Data type mi
4440: 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e  smatch */.#defin
4450: 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20  e SQLITE_MISUSE 
4460: 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62       21   /* Lib
4470: 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72  rary used incorr
4480: 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ectly */.#define
4490: 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20   SQLITE_NOLFS   
44a0: 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73      22   /* Uses
44b0: 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74   OS features not
44c0: 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f   supported on ho
44d0: 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  st */.#define SQ
44e0: 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20  LITE_AUTH       
44f0: 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69   23   /* Authori
4500: 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  zation denied */
4510: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4520: 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20  FORMAT      24  
4530: 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61   /* Auxiliary da
4540: 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72  tabase format er
4550: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
4560: 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20  QLITE_RANGE     
4570: 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61    25   /* 2nd pa
4580: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
4590: 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72  e3_bind out of r
45a0: 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ange */.#define 
45b0: 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20  SQLITE_NOTADB   
45c0: 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20     26   /* File 
45d0: 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e  opened that is n
45e0: 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69  ot a database fi
45f0: 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  le */.#define SQ
4600: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20  LITE_ROW        
4610: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33   100  /* sqlite3
4620: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74  _step() has anot
4630: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f  her row ready */
4640: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4650: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20  DONE        101 
4660: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
4670: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  () has finished 
4680: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20  executing */./* 
4690: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  end-of-error-cod
46a0: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  es */../*.** CAP
46b0: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20  I3REF: Extended 
46c0: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
46d0: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
46e0: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20  ded error code} 
46f0: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
4700: 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  codes}.** KEYWOR
4710: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4720: 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 65  sult code} {exte
4730: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4740: 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20  s}.**.** In its 
4750: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
4760: 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50  ation, SQLite AP
4770: 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  I routines retur
4780: 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65  n one of 26 inte
4790: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ger.** [SQLITE_O
47a0: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
47b0: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70  ].  However, exp
47c0: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77  erience has show
47d0: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a  n that many of.*
47e0: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63  * these result c
47f0: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61  odes are too coa
4800: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68  rse-grained.  Th
4810: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64  ey do not provid
4820: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66  e as.** much inf
4830: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70  ormation about p
4840: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72  roblems as progr
4850: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b  ammers might lik
4860: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74  e.  In an effort
4870: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74   to.** address t
4880: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69  his, newer versi
4890: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76  ons of SQLite (v
48a0: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64  ersion 3.3.8 and
48b0: 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a   later) include.
48c0: 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61  ** support for a
48d0: 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74  dditional result
48e0: 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76   codes that prov
48f0: 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65  ide more detaile
4900: 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  d information.**
4910: 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54   about errors. T
4920: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
4930: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61  lt codes are ena
4940: 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
4950: 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74  .** on a per dat
4960: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
4970: 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65   basis using the
4980: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
4990: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
49a0: 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a  es()] API..**.**
49b0: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61   Some of the ava
49c0: 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20  ilable extended 
49d0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
49e0: 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a   listed here..**
49f0: 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20   One may expect 
4a00: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78  the number of ex
4a10: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4a20: 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61  des will be expa
4a30: 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e  nd.** over time.
4a40: 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
4a50: 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 65  uses extended re
4a60: 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c  sult codes shoul
4a70: 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73  d expect.** to s
4a80: 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f  ee new result co
4a90: 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65  des in future re
4aa0: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
4ab0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
4ac0: 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64  TE_OK result cod
4ad0: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20  e will never be 
4ae0: 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69  extended.  It wi
4af0: 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ll always.** be 
4b00: 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f  exactly zero..*/
4b10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b20: 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20  IOERR_READ      
4b30: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4b40: 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a  IOERR | (1<<8)).
4b50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4b60: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
4b70: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4b80: 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23  OERR | (2<<8)).#
4b90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4ba0: 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20  ERR_WRITE       
4bb0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4bc0: 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  ERR | (3<<8)).#d
4bd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4be0: 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20  RR_FSYNC        
4bf0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4c00: 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  RR | (4<<8)).#de
4c10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4c20: 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20  R_DIR_FSYNC     
4c30: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4c40: 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66  R | (5<<8)).#def
4c50: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4c60: 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 20  _TRUNCATE       
4c70: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4c80: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69   | (6<<8)).#defi
4c90: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4ca0: 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20 20  FSTAT           
4cb0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4cc0: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (7<<8)).#defin
4cd0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55  e SQLITE_IOERR_U
4ce0: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  NLOCK           
4cf0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4d00: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
4d10: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44   SQLITE_IOERR_RD
4d20: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
4d30: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4d40: 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (9<<8)).#define 
4d50: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c  SQLITE_IOERR_DEL
4d60: 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 28  ETE            (
4d70: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4d80: 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  10<<8)).#define 
4d90: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
4da0: 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 28  CKED           (
4db0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4dc0: 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  11<<8)).#define 
4dd0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d  SQLITE_IOERR_NOM
4de0: 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 28  EM             (
4df0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4e00: 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  12<<8)).#define 
4e10: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43  SQLITE_IOERR_ACC
4e20: 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20 28  ESS            (
4e30: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4e40: 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  13<<8)).#define 
4e50: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45  SQLITE_IOERR_CHE
4e60: 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28  CKRESERVEDLOCK (
4e70: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4e80: 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  14<<8)).#define 
4e90: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43  SQLITE_IOERR_LOC
4ea0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
4eb0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4ec0: 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  15<<8)).#define 
4ed0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f  SQLITE_IOERR_CLO
4ee0: 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28  SE             (
4ef0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4f00: 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  16<<8)).#define 
4f10: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
4f20: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28  _CLOSE         (
4f30: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4f40: 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  17<<8)).#define 
4f50: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
4f60: 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20 28  OPEN           (
4f70: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4f80: 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  18<<8)).#define 
4f90: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
4fa0: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 28  SIZE           (
4fb0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4fc0: 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  19<<8)).#define 
4fd0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
4fe0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 28  LOCK           (
4ff0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5000: 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  20<<8)).#define 
5010: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5020: 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20 28  MAP            (
5030: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5040: 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  21<<8)).#define 
5050: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45  SQLITE_IOERR_SEE
5060: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
5070: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5080: 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  22<<8)).#define 
5090: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48  SQLITE_LOCKED_SH
50a0: 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 28  AREDCACHE      (
50b0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20  SQLITE_LOCKED | 
50c0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
50d0: 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43   SQLITE_BUSY_REC
50e0: 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20 20  OVERY           
50f0: 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c  (SQLITE_BUSY   |
5100: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
5110: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
5120: 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20  N_NOTEMPDIR     
5130: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
5140: 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  N | (1<<8)).#def
5150: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55  ine SQLITE_CORRU
5160: 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  PT_VTAB         
5170: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 55     (SQLITE_CORRU
5180: 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  PT | (1<<8)).#de
5190: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
51a0: 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 20  ONLY_RECOVERY   
51b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
51c0: 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23  ONLY | (1<<8)).#
51d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
51e0: 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20  ADONLY_CANTLOCK 
51f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
5200: 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29  ADONLY | (2<<8))
5210: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5220: 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65  : Flags For File
5230: 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73   Open Operations
5240: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74  .**.** These bit
5250: 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65   values are inte
5260: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
5270: 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d  the.** 3rd param
5280: 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  eter to the [sql
5290: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
52a0: 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a  interface and.**
52b0: 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 61   in the 4th para
52c0: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
52d0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
52e0: 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66   method..*/.#def
52f0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5300: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20  READONLY        
5310: 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20   0x00000001  /* 
5320: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5330: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5340: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5350: 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20  READWRITE       
5360: 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20   0x00000002  /* 
5370: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5380: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5390: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
53a0: 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20  CREATE          
53b0: 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20   0x00000004  /* 
53c0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
53d0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
53e0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
53f0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20  DELETEONCLOSE   
5400: 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20   0x00000008  /* 
5410: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5430: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20  EXCLUSIVE       
5440: 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20   0x00000010  /* 
5450: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5460: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5470: 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20  AUTOPROXY       
5480: 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20   0x00000020  /* 
5490: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
54a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
54b0: 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20 20  URI             
54c0: 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a 20   0x00000040  /* 
54d0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
54e0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
54f0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5500: 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20  MAIN_DB         
5510: 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20   0x00000100  /* 
5520: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5530: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5540: 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20  TEMP_DB         
5550: 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20   0x00000200  /* 
5560: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5570: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5580: 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20  TRANSIENT_DB    
5590: 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20   0x00000400  /* 
55a0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
55b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
55c0: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  MAIN_JOURNAL    
55d0: 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20   0x00000800  /* 
55e0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
55f0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5600: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  TEMP_JOURNAL    
5610: 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20   0x00001000  /* 
5620: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5630: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5640: 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20  SUBJOURNAL      
5650: 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20   0x00002000  /* 
5660: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
5670: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5680: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20  MASTER_JOURNAL  
5690: 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20   0x00004000  /* 
56a0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
56b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
56c0: 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20  NOMUTEX         
56d0: 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20   0x00008000  /* 
56e0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
56f0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5700: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5710: 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20  FULLMUTEX       
5720: 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20   0x00010000  /* 
5730: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5740: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
5750: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5760: 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20  SHAREDCACHE     
5770: 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20   0x00020000  /* 
5780: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
5790: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
57a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
57b0: 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20  PRIVATECACHE    
57c0: 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20   0x00040000  /* 
57d0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
57e0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
57f0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
5800: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20  WAL             
5810: 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a 20   0x00080000  /* 
5820: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20  VFS only */../* 
5830: 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20 20  Reserved:       
5840: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5850: 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f 0a    0x00F00000 */.
5860: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
5870: 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65   Device Characte
5880: 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68  ristics.**.** Th
5890: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
58a0: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 20  eristics method 
58b0: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
58c0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f  io_methods].** o
58d0: 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e  bject returns an
58e0: 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
58f0: 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68  s a vector of th
5900: 65 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76  e these.** bit v
5910: 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67  alues expressing
5920: 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73   I/O characteris
5930: 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73  tics of the mass
5940: 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69   storage.** devi
5950: 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68  ce that holds th
5960: 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20  e file that the 
5970: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
5980: 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74  ods].** refers t
5990: 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  o..**.** The SQL
59a0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
59b0: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
59c0: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
59d0: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
59e0: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
59f0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5a00: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
5a10: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
5a20: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
5a30: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
5a40: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
5a50: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
5a60: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
5a70: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
5a80: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
5a90: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
5aa0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
5ab0: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
5ac0: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
5ad0: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
5ae0: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
5af0: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
5b00: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
5b10: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
5b20: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
5b30: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
5b40: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
5b50: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
5b60: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
5b70: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
5b80: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
5b90: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
5ba0: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
5bb0: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
5bc0: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20  ** to xWrite(). 
5bd0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5be0: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
5bf0: 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d  WRITE property m
5c00: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74  eans that.** aft
5c10: 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77  er reboot follow
5c20: 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20 70  ing a crash or p
5c30: 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f  ower loss, the o
5c40: 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a  nly bytes in a.*
5c50: 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72 65  * file that were
5c60: 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65 20   written at the 
5c70: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65  application leve
5c80: 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68 61  l might have cha
5c90: 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74  nged.** and that
5ca0: 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c   adjacent bytes,
5cb0: 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74 68   even bytes with
5cc0: 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63 74  in the same sect
5cd0: 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e  or are.** guaran
5ce0: 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61  teed to be uncha
5cf0: 6e 67 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  nged..*/.#define
5d00: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5d10: 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20  OMIC            
5d20: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a       0x00000001.
5d30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5d40: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20  OCAP_ATOMIC512  
5d50: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5d60: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  000002.#define S
5d70: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5d80: 49 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC1K            
5d90: 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64     0x00000004.#d
5da0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5db0: 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20  AP_ATOMIC2K     
5dc0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5dd0: 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c  0008.#define SQL
5de0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5df0: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
5e00: 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66   0x00000010.#def
5e10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5e20: 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20  _ATOMIC8K       
5e30: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5e40: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  20.#define SQLIT
5e50: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
5e60: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
5e70: 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e  x00000040.#defin
5e80: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5e90: 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20  TOMIC32K        
5ea0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
5eb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ec0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20  IOCAP_ATOMIC64K 
5ed0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
5ee0: 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20  0000100.#define 
5ef0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
5f00: 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20  E_APPEND        
5f10: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23      0x00000200.#
5f20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5f30: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20  CAP_SEQUENTIAL  
5f40: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5f50: 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00400.#define SQ
5f60: 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c  LITE_IOCAP_UNDEL
5f70: 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e  ETABLE_WHEN_OPEN
5f80: 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65    0x00000800.#de
5f90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5fa0: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
5fb0: 57 52 49 54 45 20 20 20 20 30 78 30 30 30 30 31  WRITE    0x00001
5fc0: 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  000../*.** CAPI3
5fd0: 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e  REF: File Lockin
5fe0: 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53  g Levels.**.** S
5ff0: 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f  QLite uses one o
6000: 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
6010: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
6020: 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  cond.** argument
6030: 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b   to calls it mak
6040: 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28  es to the xLock(
6050: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
6060: 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e  methods.** of an
6070: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6080: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  hods] object..*/
6090: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
60a0: 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20  LOCK_NONE       
60b0: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
60c0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20  ITE_LOCK_SHARED 
60d0: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
60e0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53   SQLITE_LOCK_RES
60f0: 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65  ERVED      2.#de
6100: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6110: 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33  _PENDING       3
6120: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6130: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20  LOCK_EXCLUSIVE  
6140: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
6150: 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a  3REF: Synchroniz
6160: 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73  ation Type Flags
6170: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
6180: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
6190: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
61a0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
61b0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
61c0: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
61d0: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
61e0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
61f0: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
6200: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
6210: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
6220: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
6230: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
6240: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
6250: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
6260: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
6270: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
6280: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
6290: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
62a0: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
62b0: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f  ushed. If the lo
62c0: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66  wer four bits of
62d0: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75   the flag.** equ
62e0: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  al SQLITE_SYNC_N
62f0: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e  ORMAL, that mean
6300: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  s to use normal 
6310: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
6320: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77  s..** If the low
6330: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75  er four bits equ
6340: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  al SQLITE_SYNC_F
6350: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ULL, that means.
6360: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
6370: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
6380: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
6390: 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e  nc()..**.** Do n
63a0: 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53  ot confuse the S
63b0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
63c0: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
63d0: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20  C_FULL flags.** 
63e0: 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41  with the [PRAGMA
63f0: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f   synchronous]=NO
6400: 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41  RMAL and [PRAGMA
6410: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55   synchronous]=FU
6420: 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20  LL.** settings. 
6430: 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75   The [synchronou
6440: 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d  s pragma] determ
6450: 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20  ines when calls 
6460: 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20  to the.** xSync 
6470: 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72  VFS method occur
6480: 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69   and applies uni
6490: 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c  formly across al
64a0: 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20  l platforms..** 
64b0: 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  The SQLITE_SYNC_
64c0: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
64d0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
64e0: 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a  s determine how.
64f0: 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20  ** energetic or 
6500: 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63  rigorous or forc
6510: 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70  eful the sync op
6520: 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64  erations are and
6530: 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20  .** only make a 
6540: 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61  difference on Ma
6550: 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65  c OSX for the de
6560: 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64  fault SQLite cod
6570: 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72  e..** (Third-par
6580: 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ty VFS implement
6590: 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73  ations might als
65a0: 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  o make the disti
65b0: 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65  nction.** betwee
65c0: 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  n SQLITE_SYNC_NO
65d0: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
65e0: 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61  SYNC_FULL, but a
65f0: 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72  mong the.** oper
6600: 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61  ating systems na
6610: 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64  tively supported
6620: 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79   by SQLite, only
6630: 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65   Mac OSX.** care
6640: 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66  s about the diff
6650: 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66  erence.).*/.#def
6660: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
6670: 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78  NORMAL        0x
6680: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
6690: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20  LITE_SYNC_FULL  
66a0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a          0x00003.
66b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
66c0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20  YNC_DATAONLY    
66d0: 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a    0x00010../*.**
66e0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
66f0: 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c  terface Open Fil
6700: 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41  e Handle.**.** A
6710: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
6720: 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
6730: 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ts an open file 
6740: 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  in the .** [sqli
6750: 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74  te3_vfs | OS int
6760: 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20  erface layer].  
6770: 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e  Individual OS in
6780: 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65  terface.** imple
6790: 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a  mentations will.
67a0: 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c  ** want to subcl
67b0: 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20  ass this object 
67c0: 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64  by appending add
67d0: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a  itional fields.*
67e0: 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20  * for their own 
67f0: 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f  use.  The pMetho
6800: 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f  ds entry is a po
6810: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
6820: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6830: 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  ds] object that 
6840: 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20  defines methods 
6850: 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a  for performing.*
6860: 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  * I/O operations
6870: 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c   on the open fil
6880: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  e..*/.typedef st
6890: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
68a0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a  e sqlite3_file;.
68b0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
68c0: 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74  ile {.  const st
68d0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
68e0: 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64  methods *pMethod
68f0: 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  s;  /* Methods f
6900: 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  or an open file 
6910: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
6920: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
6930: 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c  ace File Virtual
6940: 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a   Methods Object.
6950: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65  **.** Every file
6960: 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b   opened by the [
6970: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
6980: 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61  n] method popula
6990: 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74  tes an.** [sqlit
69a0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
69b0: 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e  (or, more common
69c0: 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f  ly, a subclass o
69d0: 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
69e0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20  3_file] object) 
69f0: 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74  with a pointer t
6a00: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
6a10: 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a   this object..**
6a20: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   This object def
6a30: 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73  ines the methods
6a40: 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d   used to perform
6a50: 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69   various operati
6a60: 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74  ons.** against t
6a70: 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70  he open file rep
6a80: 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20  resented by the 
6a90: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
6aa0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  bject..**.** If 
6ab0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
6ac0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73  .xOpen] method s
6ad0: 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ets the sqlite3_
6ae0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
6af0: 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e  ement .** to a n
6b00: 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
6b10: 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
6b20: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c  3_io_methods.xCl
6b30: 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61  ose method.** ma
6b40: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65  y be invoked eve
6b50: 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n if the [sqlite
6b60: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70  3_vfs.xOpen] rep
6b70: 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66 61  orted that it fa
6b80: 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e  iled.  The.** on
6b90: 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e  ly way to preven
6ba0: 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f  t a call to xClo
6bb0: 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66  se following a f
6bc0: 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76  ailed [sqlite3_v
6bd0: 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20  fs.xOpen].** is 
6be0: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
6bf0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73  _vfs.xOpen] to s
6c00: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
6c10: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65  ile.pMethods ele
6c20: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e  ment.** to NULL.
6c30: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
6c40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79   argument to xSy
6c50: 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66  nc may be one of
6c60: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f   [SQLITE_SYNC_NO
6c70: 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  RMAL] or.** [SQL
6c80: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20  ITE_SYNC_FULL]. 
6c90: 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63   The first choic
6ca0: 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20  e is the normal 
6cb0: 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20  fsync()..** The 
6cc0: 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73  second choice is
6cd0: 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c   a Mac OS X styl
6ce0: 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65  e fullsync.  The
6cf0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41   [SQLITE_SYNC_DA
6d00: 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20  TAONLY].** flag 
6d10: 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74  may be ORed in t
6d20: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
6d30: 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66  only the data of
6d40: 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64   the file.** and
6d50: 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e   not its inode n
6d60: 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65  eeds to be synce
6d70: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  d..**.** The int
6d80: 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78  eger values to x
6d90: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
6da0: 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a  ck() are one of.
6db0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
6dc0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
6dd0: 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
6de0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
6df0: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
6e00: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
6e10: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
6e20: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
6e30: 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
6e40: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
6e50: 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  VE]..** </ul>.**
6e60: 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73   xLock() increas
6e70: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e  es the lock. xUn
6e80: 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73  lock() decreases
6e90: 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68   the lock..** Th
6ea0: 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  e xCheckReserved
6eb0: 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68  Lock() method ch
6ec0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79  ecks whether any
6ed0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
6ee0: 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20  tion,.** either 
6ef0: 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  in this process 
6f00: 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72  or in some other
6f10: 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c   process, is hol
6f20: 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c  ding a RESERVED,
6f30: 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20  .** PENDING, or 
6f40: 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f  EXCLUSIVE lock o
6f50: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20  n the file.  It 
6f60: 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20  returns true.** 
6f70: 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65  if such a lock e
6f80: 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20  xists and false 
6f90: 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a  otherwise..**.**
6fa0: 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   The xFileContro
6fb0: 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20  l() method is a 
6fc0: 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63  generic interfac
6fd0: 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75  e that allows cu
6fe0: 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c  stom.** VFS impl
6ff0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64  ementations to d
7000: 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20  irectly control 
7010: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69  an open file usi
7020: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
7030: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
7040: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  )] interface.  T
7050: 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61  he second "op" a
7060: 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a  rgument is an.**
7070: 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e   integer opcode.
7080: 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
7090: 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69  ment is a generi
70a0: 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64  c pointer intend
70b0: 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74  ed to.** point t
70c0: 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68  o a structure th
70d0: 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61  at may contain a
70e0: 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63  rguments or spac
70f0: 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a  e in which to.**
7100: 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61   write return va
7110: 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c  lues.  Potential
7120: 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43   uses for xFileC
7130: 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62  ontrol() might b
7140: 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74  e.** functions t
7150: 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e  o enable blockin
7160: 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d  g locks with tim
7170: 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65  eouts, to change
7180: 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20   the.** locking 
7190: 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78  strategy (for ex
71a0: 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74  ample to use dot
71b0: 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f  -file locks), to
71c0: 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75   inquire.** abou
71d0: 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20  t the status of 
71e0: 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72  a lock, or to br
71f0: 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e  eak stale locks.
7200: 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20    The SQLite.** 
7210: 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c  core reserves al
7220: 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74  l opcodes less t
7230: 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20  han 100 for its 
7240: 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53  own use..** A [S
7250: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
7260: 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20  STATE | list of 
7270: 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68  opcodes] less th
7280: 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61  an 100 is availa
7290: 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ble..** Applicat
72a0: 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65  ions that define
72b0: 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43   a custom xFileC
72c0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68  ontrol method sh
72d0: 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73  ould use opcodes
72e0: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e  .** greater than
72f0: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f   100 to avoid co
7300: 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d  nflicts.  VFS im
7310: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
7320: 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
7330: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
7340: 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f   for file contro
7350: 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74  l opcodes that t
7360: 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65  hey do not.** re
7370: 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54  cognize..**.** T
7380: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29  he xSectorSize()
7390: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
73a0: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  the sector size 
73b0: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65  of the.** device
73c0: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20   that underlies 
73d0: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73  the file.  The s
73e0: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68  ector size is th
73f0: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69  e.** minimum wri
7400: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70  te that can be p
7410: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74  erformed without
7420: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f   disturbing.** o
7430: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68  ther bytes in th
7440: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65  e file.  The xDe
7450: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
7460: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ics().** method 
7470: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65  returns a bit ve
7480: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20  ctor describing 
7490: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65  behaviors of the
74a0: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64  .** underlying d
74b0: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  evice:.**.** <ul
74c0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
74d0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a  E_IOCAP_ATOMIC].
74e0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
74f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d  IOCAP_ATOMIC512]
7500: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7510: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d  _IOCAP_ATOMIC1K]
7520: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7530: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d  _IOCAP_ATOMIC2K]
7540: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7550: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d  _IOCAP_ATOMIC4K]
7560: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7570: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d  _IOCAP_ATOMIC8K]
7580: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7590: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
75a0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
75b0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
75c0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
75d0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
75e0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
75f0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
7600: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  PPEND].** <li> [
7610: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
7620: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  UENTIAL].** </ul
7630: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
7640: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
7650: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
7660: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
7670: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
7680: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
7690: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
76a0: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
76b0: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
76c0: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
76d0: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
76e0: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
76f0: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
7700: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
7710: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
7720: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
7730: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
7740: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
7750: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
7760: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
7770: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
7780: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
7790: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
77a0: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
77b0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
77c0: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
77d0: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
77e0: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
77f0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
7800: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
7810: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
7820: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
7830: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
7840: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
7850: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
7860: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
7870: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20  *.** If xRead() 
7880: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49  returns SQLITE_I
7890: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
78a0: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c  it must also fil
78b0: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65  l.** in the unre
78c0: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74  ad portions of t
78d0: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a  he buffer with z
78e0: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61  eros.  A VFS tha
78f0: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65  t.** fails to ze
7900: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
7910: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74  ads might seem t
7920: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72  o work.  However
7930: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20  ,.** failure to 
7940: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
7950: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74  reads will event
7960: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a  ually lead to.**
7970: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   database corrup
7980: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
7990: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
79a0: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  io_methods sqlit
79b0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73  e3_io_methods;.s
79c0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
79d0: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74  _methods {.  int
79e0: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
79f0: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
7a00: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
7a10: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65   (*xRead)(sqlite
7a20: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20  3_file*, void*, 
7a30: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
7a40: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
7a50: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28    int (*xWrite)(
7a60: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63  sqlite3_file*, c
7a70: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
7a80: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
7a90: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
7aa0: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73  t (*xTruncate)(s
7ab0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
7ac0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65  lite3_int64 size
7ad0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
7ae0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7af0: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69   int flags);.  i
7b00: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28  nt (*xFileSize)(
7b10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
7b20: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53  qlite3_int64 *pS
7b30: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c  ize);.  int (*xL
7b40: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
7b50: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
7b60: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74  (*xUnlock)(sqlit
7b70: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
7b80: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65    int (*xCheckRe
7b90: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69  servedLock)(sqli
7ba0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a  te3_file*, int *
7bb0: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
7bc0: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28  (*xFileControl)(
7bd0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7be0: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72  nt op, void *pAr
7bf0: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63  g);.  int (*xSec
7c00: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33  torSize)(sqlite3
7c10: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
7c20: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65  *xDeviceCharacte
7c30: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33  ristics)(sqlite3
7c40: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65  _file*);.  /* Me
7c50: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
7c60: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
7c70: 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 1 */.  int (*x
7c80: 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f  ShmMap)(sqlite3_
7c90: 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20  file*, int iPg, 
7ca0: 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76  int pgsz, int, v
7cb0: 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b  oid volatile**);
7cc0: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63  .  int (*xShmLoc
7cd0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
7ce0: 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e  , int offset, in
7cf0: 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  t n, int flags);
7d00: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61  .  void (*xShmBa
7d10: 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66  rrier)(sqlite3_f
7d20: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
7d30: 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65  ShmUnmap)(sqlite
7d40: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c  3_file*, int del
7d50: 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d  eteFlag);.  /* M
7d60: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
7d70: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
7d80: 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a 20 41 64 64  on 2 */.  /* Add
7d90: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
7da0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
7db0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
7dc0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
7dd0: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
7de0: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
7df0: 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  odes.**.** These
7e00: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
7e10: 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66  ts are opcodes f
7e20: 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  or the xFileCont
7e30: 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66  rol method.** of
7e40: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
7e50: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
7e60: 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71   and for the [sq
7e70: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
7e80: 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  ol()].** interfa
7e90: 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ce..**.** The [S
7ea0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
7eb0: 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  STATE] opcode is
7ec0: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
7ed0: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
7ee0: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
7ef0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
7f00: 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65  hod to write the
7f10: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f   current state o
7f20: 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f  f.** the lock (o
7f30: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f  ne of [SQLITE_LO
7f40: 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  CK_NONE], [SQLIT
7f50: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a  E_LOCK_SHARED],.
7f60: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ** [SQLITE_LOCK_
7f70: 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49  RESERVED], [SQLI
7f80: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
7f90: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  , or [SQLITE_LOC
7fa0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a  K_EXCLUSIVE]).**
7fb0: 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72   into an integer
7fc0: 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61   that the pArg a
7fd0: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
7fe0: 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69  o. This capabili
7ff0: 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75  ty.** is used du
8000: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64  ring testing and
8010: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62   only needs to b
8020: 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e  e supported when
8030: 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20   SQLITE_TEST.** 
8040: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  is defined..**.*
8050: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
8060: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f  NTL_SIZE_HINT] o
8070: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 62 79  pcode is used by
8080: 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20   SQLite to give 
8090: 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72  the VFS.** layer
80a0: 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c   a hint of how l
80b0: 61 72 67 65 20 74 68 65 20 64 61 74 61 62 61 73  arge the databas
80c0: 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77  e file will grow
80d0: 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68   to be during th
80e0: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61  e.** current tra
80f0: 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20  nsaction.  This 
8100: 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72  hint is not guar
8110: 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63 63  anteed to be acc
8120: 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20  urate but it.** 
8130: 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20  is often close. 
8140: 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   The underlying 
8150: 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65  VFS might choose
8160: 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20   to preallocate 
8170: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
8180: 20 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20   space based on 
8190: 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64  this hint in ord
81a0: 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65  er to help write
81b0: 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  s to the databas
81c0: 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61  e.** file run fa
81d0: 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ster..**.** The 
81e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48  [SQLITE_FCNTL_CH
81f0: 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65  UNK_SIZE] opcode
8200: 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75   is used to requ
8210: 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53  est that the VFS
8220: 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20  .** extends and 
8230: 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61  truncates the da
8240: 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63  tabase file in c
8250: 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20  hunks of a size 
8260: 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
8270: 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f  the user. The fo
8280: 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
8290: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
82a0: 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64  ontrol()] should
82b0: 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e   .** point to an
82c0: 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69   integer (type i
82d0: 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  nt) containing t
82e0: 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a  he new chunk-siz
82f0: 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20  e to use.** for 
8300: 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61  the nominated da
8310: 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69  tabase. Allocati
8320: 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ng database file
8330: 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a   space in large.
8340: 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31  ** chunks (say 1
8350: 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d  MB at a time), m
8360: 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73  ay reduce file-s
8370: 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74  ystem fragmentat
8380: 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f  ion and.** impro
8390: 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f  ve performance o
83a0: 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a  n some systems..
83b0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
83c0: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
83d0: 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20  NTER] opcode is 
83e0: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61  used to obtain a
83f0: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
8400: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
8410: 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61  ] object associa
8420: 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69  ted with a parti
8430: 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a  cular database.*
8440: 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53  * connection.  S
8450: 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ee the [sqlite3_
8460: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
8470: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
8480: 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
8490: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
84a0: 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45  ** ^(The [SQLITE
84b0: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
84c0: 54 45 44 5d 20 6f 70 63 6f 64 65 20 69 73 20 67  TED] opcode is g
84d0: 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61  enerated interna
84e0: 6c 6c 79 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65  lly by.** SQLite
84f0: 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 61 6c 6c   and sent to all
8500: 20 56 46 53 65 73 20 69 6e 20 70 6c 61 63 65 20   VFSes in place 
8510: 6f 66 20 61 20 63 61 6c 6c 20 74 6f 20 74 68 65  of a call to the
8520: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 0a 2a 2a   xSync method.**
8530: 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
8540: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61  se connection ha
8550: 73 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  s [PRAGMA synchr
8560: 6f 6e 6f 75 73 5d 20 73 65 74 20 74 6f 20 4f 46  onous] set to OF
8570: 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65 20 73 70 65  F.)^.** Some spe
8580: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 6e  cialized VFSes n
8590: 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20  eed this signal 
85a0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 6f 70 65 72  in order to oper
85b0: 61 74 65 20 63 6f 72 72 65 63 74 6c 79 0a 2a 2a  ate correctly.**
85c0: 20 77 68 65 6e 20 5b 50 52 41 47 4d 41 20 73 79   when [PRAGMA sy
85d0: 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47  nchronous | PRAG
85e0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f  MA synchronous=O
85f0: 46 46 5d 20 69 73 20 73 65 74 2c 20 62 75 74 20  FF] is set, but 
8600: 6d 6f 73 74 20 0a 2a 2a 20 56 46 53 65 73 20 64  most .** VFSes d
8610: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20  o not need this 
8620: 73 69 67 6e 61 6c 20 61 6e 64 20 73 68 6f 75 6c  signal and shoul
8630: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  d silently ignor
8640: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a  e this opcode..*
8650: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
8660: 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b  hould not call [
8670: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
8680: 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69  trol()] with thi
8690: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 73 20 64  s.** opcode as d
86a0: 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72  oing so may disr
86b0: 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f  upt the operatio
86c0: 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c  n of the special
86d0: 69 7a 65 64 20 56 46 53 65 73 0a 2a 2a 20 74 68  ized VFSes.** th
86e0: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
86f0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  .  .**.** ^The [
8700: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
8710: 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63  32_AV_RETRY] opc
8720: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63  ode is used to c
8730: 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74  onfigure automat
8740: 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e  ic.** retry coun
8750: 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73  ts and intervals
8760: 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73   for certain dis
8770: 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  k I/O operations
8780: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64   for the.** wind
8790: 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64  ows [VFS] in ord
87a0: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f  er to provide ro
87b0: 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20  bustness in the 
87c0: 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61  presence of.** a
87d0: 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61  nti-virus progra
87e0: 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ms.  By default,
87f0: 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53   the windows VFS
8800: 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65   will retry file
8810: 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77   read,.** file w
8820: 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64  rite, and file d
8830: 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73  elete operations
8840: 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c   up to 10 times,
8850: 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a   with a delay.**
8860: 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f   of 25 milliseco
8870: 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66  nds before the f
8880: 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77  irst retry and w
8890: 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e  ith the delay in
88a0: 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61  creasing.** by a
88b0: 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20  n additional 25 
88c0: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74  milliseconds wit
88d0: 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e  h each subsequen
88e0: 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a  t retry.  This.*
88f0: 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20  * opcode allows 
8900: 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73  these two values
8910: 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64   (10 retries and
8920: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
8930: 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f   of delay).** to
8940: 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54   be adjusted.  T
8950: 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68  he values are ch
8960: 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61  anged for all da
8970: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
8980: 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65  ns.** within the
8990: 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20   same process.  
89a0: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
89b0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
89c0: 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20  array of two.** 
89d0: 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74  integers where t
89e0: 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72  he first integer
89f0: 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79   i the new retry
8a00: 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73   count and the s
8a10: 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72  econd.** integer
8a20: 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20   is the delay.  
8a30: 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65  If either intege
8a40: 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
8a50: 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a  hen the setting.
8a60: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  ** is not change
8a70: 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68  d but instead th
8a80: 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
8a90: 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73   that setting is
8aa0: 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f   written.** into
8ab0: 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79   the array entry
8ac0: 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63  , allowing the c
8ad0: 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74  urrent retry set
8ae0: 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69  tings to be.** i
8af0: 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68  nterrogated.  Th
8b00: 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65  e zDbName parame
8b10: 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  ter is ignored..
8b20: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
8b30: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
8b40: 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20  _WAL] opcode is 
8b50: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71  used to set or q
8b60: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73  uery the.** pers
8b70: 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72  istent [WAL | Wr
8b80: 69 74 65 20 41 48 65 61 64 20 4c 6f 67 5d 20 73  ite AHead Log] s
8b90: 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61  etting.  By defa
8ba0: 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61  ult, the auxilia
8bb0: 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61  ry.** write ahea
8bc0: 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64  d log and shared
8bd0: 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73   memory files us
8be0: 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69  ed for transacti
8bf0: 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72  on control.** ar
8c00: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
8c10: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65  deleted when the
8c20: 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69   latest connecti
8c30: 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  on to the databa
8c40: 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53  se.** closes.  S
8c50: 65 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e  etting persisten
8c60: 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65  t WAL mode cause
8c70: 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f  s those files to
8c80: 20 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a   persist after.*
8c90: 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73  * close.  Persis
8ca0: 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69  ting the files i
8cb0: 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74  s useful when ot
8cc0: 68 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68  her processes th
8cd0: 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76  at do not.** hav
8ce0: 65 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69  e write permissi
8cf0: 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74  on on the direct
8d00: 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ory containing t
8d10: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
8d20: 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64   want.** to read
8d30: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
8d40: 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61  le, as the WAL a
8d50: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79  nd shared memory
8d60: 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73   files must exis
8d70: 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f  t.** in order fo
8d80: 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74  r the database t
8d90: 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20  o be readable.  
8da0: 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
8db0: 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
8dc0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
8dd0: 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63  ()] for this opc
8de0: 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ode should be a 
8df0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
8e00: 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69  teger..** That i
8e10: 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64  nteger is 0 to d
8e20: 69 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e  isable persisten
8e30: 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20  t WAL mode or 1 
8e40: 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73  to enable persis
8e50: 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65  tent.** WAL mode
8e60: 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65  .  If the intege
8e70: 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74  r is -1, then it
8e80: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
8e90: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
8ea0: 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65  .** WAL persiste
8eb0: 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  nce setting..**.
8ec0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
8ed0: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
8ee0: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64  OVERWRITE] opcod
8ef0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
8f00: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
8f10: 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77   persistent "pow
8f20: 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65  ersafe-overwrite
8f30: 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74  " or "PSOW" sett
8f40: 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73  ing.  The PSOW s
8f50: 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d  etting.** determ
8f60: 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45  ines the [SQLITE
8f70: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
8f80: 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20  _OVERWRITE] bit 
8f90: 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63  of the.** xDevic
8fa0: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
8fb0: 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f   methods. The fo
8fc0: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
8fd0: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  o.** [sqlite3_fi
8fe0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f  le_control()] fo
8ff0: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68  r this opcode sh
9000: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65  ould be a pointe
9010: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e  r to an integer.
9020: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72  .** That integer
9030: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
9040: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64   zero-damage mod
9050: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65  e or 1 to enable
9060: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20   zero-damage.** 
9070: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
9080: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
9090: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
90a0: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
90b0: 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d  rent.** zero-dam
90c0: 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67  age mode setting
90d0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ..**.** ^The [SQ
90e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
90f0: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  RITE] opcode is 
9100: 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74  invoked by SQLit
9110: 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a  e after opening.
9120: 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e 73  ** a write trans
9130: 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61  action to indica
9140: 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20  te that, unless 
9150: 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63  it is rolled bac
9160: 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65  k for some.** re
9170: 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65  ason, the entire
9180: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
9190: 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74  ill be overwritt
91a0: 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65 6e  en by the curren
91b0: 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  t .** transactio
91c0: 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64 20  n. This is used 
91d0: 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74  by VACUUM operat
91e0: 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ions..**.** ^The
91f0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56   [SQLITE_FCNTL_V
9200: 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63  FSNAME] opcode c
9210: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
9220: 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
9230: 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d  f.** all [VFSes]
9240: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61 63   in the VFS stac
9250: 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72  k.  The names ar
9260: 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69  e of all VFS shi
9270: 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69  ms and the.** fi
9280: 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c  nal bottom-level
9290: 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65 6e   VFS are written
92a0: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
92b0: 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  ained from .** [
92c0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
92d0: 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74  ] and the result
92e0: 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68   is stored in th
92f0: 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65  e char* variable
9300: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75  .** that the fou
9310: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66  rth parameter of
9320: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9330: 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73  ontrol()] points
9340: 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c   to..** The call
9350: 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  er is responsibl
9360: 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68  e for freeing th
9370: 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f  e memory when do
9380: 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20  ne.  As with.** 
9390: 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  all file-control
93a0: 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20   actions, there 
93b0: 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20  is no guarantee 
93c0: 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61  that this will a
93d0: 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e  ctually.** do an
93e0: 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73  ything.  Callers
93f0: 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69   should initiali
9400: 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61 72  ze the char* var
9410: 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a  iable to a NULL.
9420: 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61  ** pointer in ca
9430: 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e  se this file-con
9440: 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c  trol is not impl
9450: 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66  emented.  This f
9460: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69  ile-control.** i
9470: 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64  s intended for d
9480: 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e  iagnostic use on
9490: 6c 79 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ly..*/.#define S
94a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
94b0: 53 54 41 54 45 20 20 20 20 20 20 20 20 20 20 20  STATE           
94c0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
94d0: 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_GET_LOCKPRO
94e0: 58 59 46 49 4c 45 20 20 20 20 20 20 20 20 20 20  XYFILE          
94f0: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
9500: 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_SET_LOCKPROX
9510: 59 46 49 4c 45 20 20 20 20 20 20 20 20 20 20 20  YFILE           
9520: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
9530: 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20  TE_LAST_ERRNO   
9540: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
9550: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
9560: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
9570: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
9580: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
9590: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
95a0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  E              6
95b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
95c0: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
95d0: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 37 0a  ER            7.
95e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
95f0: 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45  CNTL_SYNC_OMITTE
9600: 44 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23  D            8.#
9610: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
9620: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
9630: 52 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  RY          9.#d
9640: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
9650: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20  TL_PERSIST_WAL  
9660: 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65            10.#de
9670: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
9680: 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 20  L_OVERWRITE     
9690: 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66           11.#def
96a0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
96b0: 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20  _VFSNAME        
96c0: 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69          12.#defi
96d0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
96e0: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
96f0: 49 54 45 20 20 20 20 31 33 0a 0a 2f 2a 0a 2a 2a  ITE    13../*.**
9700: 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78   CAPI3REF: Mutex
9710: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68   Handle.**.** Th
9720: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77  e mutex module w
9730: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66  ithin SQLite def
9740: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75  ines [sqlite3_mu
9750: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a  tex] to be an.**
9760: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66   abstract type f
9770: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63  or a mutex objec
9780: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  t.  The SQLite c
9790: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a  ore never looks.
97a0: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e  ** at the intern
97b0: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
97c0: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  n of an [sqlite3
97d0: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c  _mutex].  It onl
97e0: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20  y.** deals with 
97f0: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20  pointers to the 
9800: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
9810: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75  object..**.** Mu
9820: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65  texes are create
9830: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
9840: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e  _mutex_alloc()].
9850: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
9860: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ct sqlite3_mutex
9870: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a   sqlite3_mutex;.
9880: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
9890: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62   OS Interface Ob
98a0: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  ject.**.** An in
98b0: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71  stance of the sq
98c0: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
98d0: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
98e0: 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a  erface between.*
98f0: 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * the SQLite cor
9900: 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c  e and the underl
9910: 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73  ying operating s
9920: 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73  ystem.  The "vfs
9930: 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65  ".** in the name
9940: 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73   of the object s
9950: 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75  tands for "virtu
9960: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e  al file system".
9970: 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46    See.** the [VF
9980: 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74  S | VFS document
9990: 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68  ation] for furth
99a0: 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  er information..
99b0: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  **.** The value 
99c0: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  of the iVersion 
99d0: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
99e0: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
99f0: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74  larger in.** fut
9a00: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
9a10: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
9a20: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
9a30: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
9a40: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
9a50: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
9a60: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
9a70: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  d.  Note that th
9a80: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f  e structure.** o
9a90: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
9aa0: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73  s object changes
9ab0: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   in the transact
9ac0: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53  ion between.** S
9ad0: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
9ae0: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e  5.9 and 3.6.0 an
9af0: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69  d yet the iVersi
9b00: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74  on field was not
9b10: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  .** modified..**
9b20: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
9b30: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
9b40: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
9b50: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
9b60: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
9b70: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
9b80: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
9b90: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
9ba0: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
9bb0: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
9bc0: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
9bd0: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
9be0: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
9bf0: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
9c00: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
9c10: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
9c20: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
9c30: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
9c40: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
9c50: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
9c60: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
9c70: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
9c80: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
9c90: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
9ca0: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
9cb0: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
9cc0: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
9cd0: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70    Neither the ap
9ce0: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e  plication code n
9cf0: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d  or the VFS.** im
9d00: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
9d10: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78  uld use the pNex
9d20: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  t pointer..**.**
9d30: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64   The pNext field
9d40: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65   is the only fie
9d50: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ld in the sqlite
9d60: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75  3_vfs.** structu
9d70: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
9d80: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
9d90: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
9da0: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
9db0: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
9dc0: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
9dd0: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
9de0: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
9df0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
9e00: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
9e10: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
9e20: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
9e30: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
9e40: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
9e50: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
9e60: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
9e70: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
9e80: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
9e90: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
9ea0: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
9eb0: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
9ec0: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
9ed0: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73  ** [[sqlite3_vfs
9ee0: 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c  .xOpen]].** ^SQL
9ef0: 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74  ite guarantees t
9f00: 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d  hat the zFilenam
9f10: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
9f20: 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65  Open.** is eithe
9f30: 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
9f40: 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69   or string obtai
9f50: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c  ned.** from xFul
9f60: 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68  lPathname() with
9f70: 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66   an optional suf
9f80: 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49  fix added..** ^I
9f90: 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64  f a suffix is ad
9fa0: 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65  ded to the zFile
9fb0: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20  name parameter, 
9fc0: 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69  it will.** consi
9fd0: 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22  st of a single "
9fe0: 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c  -" character fol
9ff0: 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65  lowed by no more
a000: 20 74 68 61 6e 0a 2a 2a 20 31 30 20 61 6c 70 68   than.** 10 alph
a010: 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20  anumeric and/or 
a020: 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a  "-" characters..
a030: 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68  ** ^SQLite furth
a040: 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  er guarantees th
a050: 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  at.** the string
a060: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
a070: 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74  nd unchanged unt
a080: 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a  il xClose() is.*
a090: 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73  * called. Becaus
a0a0: 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75  e of the previou
a0b0: 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74  s sentence,.** t
a0c0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
a0d0: 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f  ] can safely sto
a0e0: 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  re a pointer to 
a0f0: 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  the.** filename 
a100: 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72  if it needs to r
a110: 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65  emember the file
a120: 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65  name for some re
a130: 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ason..** If the 
a140: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
a150: 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20  ter to xOpen is 
a160: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
a170: 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73  hen xOpen.** mus
a180: 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e  t invent its own
a190: 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20   temporary name 
a1a0: 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e  for the file.  ^
a1b0: 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a  Whenever the .**
a1c0: 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   xFilename param
a1d0: 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20  eter is NULL it 
a1e0: 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65  will also be the
a1f0: 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a   case that the.*
a200: 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  * flags paramete
a210: 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b  r will include [
a220: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
a230: 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a  TEONCLOSE]..**.*
a240: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
a250: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20  ment to xOpen() 
a260: 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74  includes all bit
a270: 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20  s set in.** the 
a280: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
a290: 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  o [sqlite3_open_
a2a0: 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73  v2()].  Or if [s
a2b0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
a2c0: 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  * or [sqlite3_op
a2d0: 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  en16()] is used,
a2e0: 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c   then flags incl
a2f0: 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a  udes at least.**
a300: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
a310: 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
a320: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e  TE_OPEN_CREATE].
a330: 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20   .** If xOpen() 
a340: 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61  opens a file rea
a350: 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73  d-only then it s
a360: 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74  ets *pOutFlags t
a370: 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51  o.** include [SQ
a380: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
a390: 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73  LY].  Other bits
a3a0: 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d   in *pOutFlags m
a3b0: 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  ay be set..**.**
a3c0: 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61   ^(SQLite will a
a3d0: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
a3e0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
a3f0: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28  gs to the xOpen(
a400: 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e  ).** call, depen
a410: 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65  ding on the obje
a420: 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a  ct being opened:
a430: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
a440: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
a450: 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_MAIN_DB].** <l
a460: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
a470: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _MAIN_JOURNAL].*
a480: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
a490: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a  OPEN_TEMP_DB].**
a4a0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
a4b0: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
a4c0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
a4d0: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
a4e0: 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  T_DB].** <li>  [
a4f0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a  SQLITE_OPEN_SUBJ
a500: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
a510: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
a520: 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  STER_JOURNAL].**
a530: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
a540: 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  PEN_WAL].** </ul
a550: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  >)^.**.** The fi
a560: 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74  le I/O implement
a570: 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68  ation can use th
a580: 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c  e object type fl
a590: 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65  ags to.** change
a5a0: 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c   the way it deal
a5b0: 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46  s with files.  F
a5c0: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  or example, an a
a5d0: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68  pplication.** th
a5e0: 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  at does not care
a5f0: 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63   about crash rec
a600: 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63  overy or rollbac
a610: 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20  k might make.** 
a620: 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f  the open of a jo
a630: 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d  urnal file a no-
a640: 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74  op.  Writes to t
a650: 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  his journal woul
a660: 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d  d.** also be no-
a670: 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74  ops, and any att
a680: 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65  empt to read the
a690: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72   journal would r
a6a0: 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f  eturn.** SQLITE_
a6b0: 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69  IOERR.  Or the i
a6c0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69  mplementation mi
a6d0: 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68  ght recognize th
a6e0: 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  at a database.**
a6f0: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f   file will be do
a700: 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64  ing page-aligned
a710: 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e   sector reads an
a720: 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61  d writes in a ra
a730: 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e  ndom.** order an
a740: 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f  d set up its I/O
a750: 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72   subsystem accor
a760: 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51  dingly..**.** SQ
a770: 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  Lite might also 
a780: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
a790: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
a7a0: 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  o the xOpen meth
a7b0: 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  od:.**.** <ul>.*
a7c0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
a7d0: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
a7e0: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  E].** <li> [SQLI
a7f0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
a800: 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  E].** </ul>.**.*
a810: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  * The [SQLITE_OP
a820: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
a830: 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65  ] flag means the
a840: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a   file should be.
a850: 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ** deleted when 
a860: 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e  it is closed.  ^
a870: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
a880: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
a890: 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66  ** will be set f
a8a0: 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65  or TEMP database
a8b0: 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72  s and their jour
a8c0: 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a  nals, transient.
a8d0: 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e  ** databases, an
a8e0: 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a  d subjournals..*
a8f0: 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
a900: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
a910: 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73  ] flag is always
a920: 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63   used in conjunc
a930: 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65  tion.** with the
a940: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
a950: 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63  EATE] flag, whic
a960: 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63  h are both direc
a970: 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73  tly.** analogous
a980: 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61   to the O_EXCL a
a990: 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73  nd O_CREAT flags
a9a0: 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70   of the POSIX op
a9b0: 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68  en().** API.  Th
a9c0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58  e SQLITE_OPEN_EX
a9d0: 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68  CLUSIVE flag, wh
a9e0: 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74  en paired with t
a9f0: 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50  he .** SQLITE_OP
aa00: 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73  EN_CREATE, is us
aa10: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
aa20: 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  hat file should 
aa30: 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65  always.** be cre
aa40: 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69  ated, and that i
aa50: 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66  t is an error if
aa60: 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73   it already exis
aa70: 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e  ts..** It is <i>
aa80: 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20  not</i> used to 
aa90: 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c  indicate the fil
aaa0: 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e  e should be open
aab0: 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75  ed .** for exclu
aac0: 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a  sive access..**.
aad0: 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f  ** ^At least szO
aae0: 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d  sFile bytes of m
aaf0: 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61  emory are alloca
ab00: 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  ted by SQLite.**
ab10: 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73   to hold the  [s
ab20: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72  qlite3_file] str
ab30: 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73  ucture passed as
ab40: 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72   the third.** ar
ab50: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e  gument to xOpen.
ab60: 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68    The xOpen meth
ab70: 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  od does not have
ab80: 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20   to.** allocate 
ab90: 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69  the structure; i
aba0: 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69  t should just fi
abb0: 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20  ll it in.  Note 
abc0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65  that.** the xOpe
abd0: 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65  n method must se
abe0: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
abf0: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65  le.pMethods to e
ac00: 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64  ither.** a valid
ac10: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
ac20: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20  hods] object or 
ac30: 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20  to NULL.  xOpen 
ac40: 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20  must do.** this 
ac50: 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e  even if the open
ac60: 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20   fails.  SQLite 
ac70: 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65  expects that the
ac80: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
ac90: 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e  ethods.** elemen
aca0: 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  t will be valid 
acb0: 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75  after xOpen retu
acc0: 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f  rns regardless o
acd0: 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a  f the success.**
ace0: 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74   or failure of t
acf0: 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a  he xOpen call..*
ad00: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
ad10: 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20  fs.xAccess]].** 
ad20: 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d  ^The flags argum
ad30: 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29  ent to xAccess()
ad40: 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f   may be [SQLITE_
ad50: 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a  ACCESS_EXISTS].*
ad60: 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68  * to test for th
ad70: 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61  e existence of a
ad80: 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54   file, or [SQLIT
ad90: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
ada0: 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77  TE] to.** test w
adb0: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
adc0: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
add0: 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  itable, or [SQLI
ade0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a  TE_ACCESS_READ].
adf0: 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68  ** to test wheth
ae00: 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20  er a file is at 
ae10: 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20  least readable. 
ae20: 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62    The file can b
ae30: 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79  e a.** directory
ae40: 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
ae50: 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f  will always allo
ae60: 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78  cate at least mx
ae70: 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73  Pathname+1 bytes
ae80: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70   for the.** outp
ae90: 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50  ut buffer xFullP
aea0: 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78  athname.  The ex
aeb0: 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20  act size of the 
aec0: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
aed0: 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20   is also passed 
aee0: 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74  as a parameter t
aef0: 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e  o both  methods.
af00: 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   If the output b
af10: 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20  uffer.** is not 
af20: 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53  large enough, [S
af30: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
af40: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
af50: 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69  ed. Since this i
af60: 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20  s.** handled as 
af70: 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79  a fatal error by
af80: 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70   SQLite, vfs imp
af90: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
afa0: 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20  uld endeavor.** 
afb0: 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20  to prevent this 
afc0: 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74  by setting mxPat
afd0: 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69  hname to a suffi
afe0: 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61  ciently large va
aff0: 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  lue..**.** The x
b000: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53  Randomness(), xS
b010: 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74  leep(), xCurrent
b020: 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72  Time(), and xCur
b030: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a  rentTimeInt64().
b040: 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  ** interfaces ar
b050: 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61  e not strictly a
b060: 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c   part of the fil
b070: 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65  esystem, but the
b080: 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65  y are.** include
b090: 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72  d in the VFS str
b0a0: 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c  ucture for compl
b0b0: 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20  eteness..** The 
b0c0: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75  xRandomness() fu
b0d0: 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20  nction attempts 
b0e0: 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73  to return nBytes
b0f0: 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f   bytes.** of goo
b100: 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d  d-quality random
b110: 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20  ness into zOut. 
b120: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
b130: 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75  e is.** the actu
b140: 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  al number of byt
b150: 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
b160: 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68   obtained..** Th
b170: 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
b180: 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  d causes the cal
b190: 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73  ling thread to s
b1a0: 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c  leep for at.** l
b1b0: 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20  east the number 
b1c0: 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20  of microseconds 
b1d0: 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75  given.  ^The xCu
b1e0: 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d  rrentTime().** m
b1f0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
b200: 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65  Julian Day Numbe
b210: 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e  r for the curren
b220: 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20  t date and time 
b230: 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67  as.** a floating
b240: 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a   point value..**
b250: 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69   ^The xCurrentTi
b260: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
b270: 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20   returns, as an 
b280: 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c  integer, the Jul
b290: 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65  ian.** Day Numbe
b2a0: 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20  r multiplied by 
b2b0: 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75  86400000 (the nu
b2c0: 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
b2d0: 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34  onds in .** a 24
b2e0: 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a  -hour day).  .**
b2f0: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
b300: 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69  e the xCurrentTi
b310: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
b320: 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72   to get the curr
b330: 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20  ent.** date and 
b340: 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74  time if that met
b350: 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65  hod is available
b360: 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73   (if iVersion is
b370: 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65   2 or .** greate
b380: 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69  r and the functi
b390: 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
b3a0: 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c  t NULL) and will
b3b0: 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f   fall back.** to
b3c0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20   xCurrentTime() 
b3d0: 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  if xCurrentTimeI
b3e0: 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69  nt64() is unavai
b3f0: 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lable..**.** ^Th
b400: 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  e xSetSystemCall
b410: 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61  (), xGetSystemCa
b420: 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53  ll(), and xNestS
b430: 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65  ystemCall() inte
b440: 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f  rfaces.** are no
b450: 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51  t used by the SQ
b460: 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73  Lite core.  Thes
b470: 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72  e optional inter
b480: 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64  faces are provid
b490: 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46  ed.** by some VF
b4a0: 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74  Ses to facilitat
b4b0: 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65  e testing of the
b4c0: 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76   VFS code. By ov
b4d0: 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73  erriding .** sys
b4e0: 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66  tem calls with f
b4f0: 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69  unctions under i
b500: 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65  ts control, a te
b510: 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a  st program can.*
b520: 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74  * simulate fault
b530: 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64  s and error cond
b540: 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c  itions that woul
b550: 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64  d otherwise be d
b560: 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69  ifficult.** or i
b570: 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64  mpossible to ind
b580: 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66  uce.  The set of
b590: 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68   system calls th
b5a0: 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69  at can be overri
b5b0: 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66  dden.** varies f
b5c0: 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61  rom one VFS to a
b5d0: 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d  nother, and from
b5e0: 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20   one version of 
b5f0: 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20  the same VFS to 
b600: 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70  the.** next.  Ap
b610: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
b620: 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66  use these interf
b630: 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65  aces must be pre
b640: 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a  pared for any.**
b650: 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65   or all of these
b660: 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62   interfaces to b
b670: 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68  e NULL or for th
b680: 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20  eir behavior to 
b690: 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f  change.** from o
b6a0: 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68  ne release to th
b6b0: 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61  e next.  Applica
b6c0: 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61  tions must not a
b6d0: 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73  ttempt to access
b6e0: 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65  .** any of these
b6f0: 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20   methods if the 
b700: 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20  iVersion of the 
b710: 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e  VFS is less than
b720: 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73   3..*/.typedef s
b730: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
b740: 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74  s sqlite3_vfs;.t
b750: 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
b760: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
b770: 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74  r)(void);.struct
b780: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20   sqlite3_vfs {. 
b790: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20   int iVersion;  
b7a0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72            /* Str
b7b0: 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e  ucture version n
b7c0: 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79  umber (currently
b7d0: 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f   3) */.  int szO
b7e0: 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20  sFile;          
b7f0: 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62    /* Size of sub
b800: 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f  classed sqlite3_
b810: 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78  file */.  int mx
b820: 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20  Pathname;       
b830: 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69     /* Maximum fi
b840: 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67  le pathname leng
b850: 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  th */.  sqlite3_
b860: 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20  vfs *pNext;     
b870: 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65   /* Next registe
b880: 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e  red VFS */.  con
b890: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20  st char *zName; 
b8a0: 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
b8b0: 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69   this virtual fi
b8c0: 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76  le system */.  v
b8d0: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
b8e0: 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74          /* Point
b8f0: 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f  er to applicatio
b900: 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20  n-specific data 
b910: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e  */.  int (*xOpen
b920: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
b930: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
b940: 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e, sqlite3_file*
b950: 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
b960: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
b970: 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69  *pOutFlags);.  i
b980: 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71  nt (*xDelete)(sq
b990: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
b9a0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
b9b0: 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69  nt syncDir);.  i
b9c0: 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71  nt (*xAccess)(sq
b9d0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
b9e0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
b9f0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
ba00: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
ba10: 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28  *xFullPathname)(
ba20: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
ba30: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
ba40: 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20   int nOut, char 
ba50: 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a  *zOut);.  void *
ba60: 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74  (*xDlOpen)(sqlit
ba70: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
ba80: 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b  har *zFilename);
ba90: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72  .  void (*xDlErr
baa0: 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
bab0: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
bac0: 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76  r *zErrMsg);.  v
bad0: 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28  oid (*(*xDlSym)(
bae0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69  sqlite3_vfs*,voi
baf0: 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  d*, const char *
bb00: 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b  zSymbol))(void);
bb10: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f  .  void (*xDlClo
bb20: 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  se)(sqlite3_vfs*
bb30: 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20  , void*);.  int 
bb40: 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73  (*xRandomness)(s
bb50: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
bb60: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f   nByte, char *zO
bb70: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c  ut);.  int (*xSl
bb80: 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73  eep)(sqlite3_vfs
bb90: 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f  *, int microseco
bba0: 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  nds);.  int (*xC
bbb0: 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69  urrentTime)(sqli
bbc0: 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65  te3_vfs*, double
bbd0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74  *);.  int (*xGet
bbe0: 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74  LastError)(sqlit
bbf0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68  e3_vfs*, int, ch
bc00: 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  ar *);.  /*.  **
bc10: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
bc20: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
bc30: 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74  n 1 of the sqlit
bc40: 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a  e_vfs object.  *
bc50: 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  * definition.  T
bc60: 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77  hose that follow
bc70: 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65   are added in ve
bc80: 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72  rsion 2 or later
bc90: 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43  .  */.  int (*xC
bca0: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29  urrentTimeInt64)
bcb0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73  (sqlite3_vfs*, s
bcc0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a  qlite3_int64*);.
bcd0: 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
bce0: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
bcf0: 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e  in versions 1 an
bd00: 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74  d 2 of the sqlit
bd10: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
bd20: 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61  ** Those below a
bd30: 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33  re for version 3
bd40: 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20   and greater..  
bd50: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53  */.  int (*xSetS
bd60: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
bd70: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
bd80: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69  har *zName, sqli
bd90: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
bda0: 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63  ;.  sqlite3_sysc
bdb0: 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79  all_ptr (*xGetSy
bdc0: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
bdd0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
bde0: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f  ar *zName);.  co
bdf0: 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78  nst char *(*xNex
be00: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
be10: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
be20: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20   char *zName);. 
be30: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
be40: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
be50: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72  n versions 1 thr
be60: 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71  ough 3 of the sq
be70: 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e  lite_vfs object.
be80: 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73  .  ** New fields
be90: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
bea0: 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69   in figure versi
beb0: 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69  ons.  The iVersi
bec0: 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69  on.  ** value wi
bed0: 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65  ll increment whe
bee0: 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65  never this happe
bef0: 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  ns. .  */.};../*
bf00: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
bf10: 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63  ags for the xAcc
bf20: 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a  ess VFS method.*
bf30: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
bf40: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e  er constants can
bf50: 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20   be used as the 
bf60: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
bf70: 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73  to.** the xAcces
bf80: 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b  s method of an [
bf90: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
bfa0: 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72  ect.  They deter
bfb0: 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e  mine.** what kin
bfc0: 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73  d of permissions
bfd0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
bfe0: 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66  hod is looking f
bff0: 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  or..** With SQLI
c000: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
c010: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
c020: 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63  thod.** simply c
c030: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
c040: 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a  e file exists..*
c050: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
c060: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20  CESS_READWRITE, 
c070: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
c080: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
c090: 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64  ther the named d
c0a0: 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68  irectory is both
c0b0: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
c0c0: 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74  itable.** (in ot
c0d0: 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69  her words, if fi
c0e0: 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64  les can be added
c0f0: 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72  , removed, and r
c100: 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a  enamed within.**
c110: 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e   the directory).
c120: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41  .** The SQLITE_A
c130: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
c140: 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72  constant is curr
c150: 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20  ently used only 
c160: 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f  by the.** [temp_
c170: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
c180: 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20  pragma], though 
c190: 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67  this could chang
c1a0: 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a  e in a future.**
c1b0: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
c1c0: 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  te..** With SQLI
c1d0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20  TE_ACCESS_READ, 
c1e0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
c1f0: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
c200: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73  ther the file is
c210: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
c220: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
c230: 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a  AD constant is.*
c240: 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73  * currently unus
c250: 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69  ed, though it mi
c260: 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61  ght be used in a
c270: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
c280: 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f  of.** SQLite..*/
c290: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c2a0: 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20  ACCESS_EXISTS   
c2b0: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
c2c0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
c2d0: 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62  TE 1   /* Used b
c2e0: 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74  y PRAGMA temp_st
c2f0: 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f  ore_directory */
c300: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c310: 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20  ACCESS_READ     
c320: 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a   2   /* Unused *
c330: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
c340: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
c350: 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65   xShmLock VFS me
c360: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
c370: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
c380: 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61  ts define the va
c390: 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70  rious locking op
c3a0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f  erations.** allo
c3b0: 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c  wed by the xShmL
c3c0: 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73  ock method of [s
c3d0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
c3e0: 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c  s].  The.** foll
c3f0: 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e  owing are the on
c400: 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61  ly legal combina
c410: 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74  tions of flags t
c420: 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63  o the.** xShmLoc
c430: 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  k method:.**.** 
c440: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  <ul>.** <li>  SQ
c450: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20  LITE_SHM_LOCK | 
c460: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
c470: 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  D.** <li>  SQLIT
c480: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
c490: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
c4a0: 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  E.** <li>  SQLIT
c4b0: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53  E_SHM_UNLOCK | S
c4c0: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
c4d0: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
c4e0: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
c4f0: 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
c500: 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VE.** </ul>.**.*
c510: 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67  * When unlocking
c520: 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45  , the same SHARE
c530: 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66  D or EXCLUSIVE f
c540: 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70  lag must be supp
c550: 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67  lied as.** was g
c560: 69 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72  iven no the corr
c570: 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20  esponding lock. 
c580: 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d   .**.** The xShm
c590: 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20  Lock method can 
c5a0: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
c5b0: 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
c5c0: 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74  SHARED or.** bet
c5d0: 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
c5e0: 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74  d EXCLUSIVE.  It
c5f0: 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69   cannot transiti
c600: 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45  on between SHARE
c610: 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49  D.** and EXCLUSI
c620: 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  VE..*/.#define S
c630: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
c640: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
c650: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
c660: 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
c670: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48  ne SQLITE_SHM_SH
c680: 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65  ARED       4.#de
c690: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
c6a0: 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a  EXCLUSIVE    8..
c6b0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
c6c0: 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b  Maximum xShmLock
c6d0: 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65   index.**.** The
c6e0: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
c6f0: 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   on [sqlite3_io_
c700: 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65  methods] may use
c710: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
c720: 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70  en 0 and this up
c730: 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73  per bound as its
c740: 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65   "offset" argume
c750: 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  nt..** The SQLit
c760: 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65  e core will neve
c770: 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71  r attempt to acq
c780: 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20  uire or release 
c790: 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64  a.** lock outsid
c7a0: 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a  e of this range.
c7b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
c7c0: 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20  E_SHM_NLOCK     
c7d0: 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     8.../*.** CAP
c7e0: 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a  I3REF: Initializ
c7f0: 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62  e The SQLite Lib
c800: 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rary.**.** ^The 
c810: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
c820: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69  ze() routine ini
c830: 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20  tializes the.** 
c840: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
c850: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68   ^The sqlite3_sh
c860: 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65  utdown() routine
c870: 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20  .** deallocates 
c880: 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68  any resources th
c890: 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65  at were allocate
c8a0: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  d by sqlite3_ini
c8b0: 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68  tialize()..** Th
c8c0: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
c8d0: 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64   designed to aid
c8e0: 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74   in process init
c8f0: 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a  ialization and.*
c900: 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d  * shutdown on em
c910: 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20  bedded systems. 
c920: 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70   Workstation app
c930: 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a  lications using.
c940: 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c  ** SQLite normal
c950: 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ly do not need t
c960: 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  o invoke either 
c970: 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
c980: 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  s..**.** A call 
c990: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
c9a0: 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65  alize() is an "e
c9b0: 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
c9c0: 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66  f it is.** the f
c9d0: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
c9e0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
c9f0: 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67  s invoked during
ca00: 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66   the lifetime of
ca10: 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c  .** the process,
ca20: 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65   or if it is the
ca30: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
ca40: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
ca50: 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66   is invoked.** f
ca60: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20  ollowing a call 
ca70: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
ca80: 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61  own().  ^(Only a
ca90: 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
caa0: 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69  .** of sqlite3_i
cab0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73  nitialize() does
cac0: 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74   any initializat
cad0: 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ion.  All other 
cae0: 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72  calls.** are har
caf0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
cb00: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
cb10: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
cb20: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
cb30: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
cb40: 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
cb50: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
cb60: 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65  shutdown() since
cb70: 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65   the last sqlite
cb80: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20  3_initialize(). 
cb90: 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66   ^(Only.** an ef
cba0: 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20  fective call to 
cbb0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
cbc0: 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e  () does any dein
cbd0: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  itialization..**
cbe0: 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64   All other valid
cbf0: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
cc00: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65  3_shutdown() are
cc10: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
cc20: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  .)^.**.** The sq
cc30: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
cc40: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
cc50: 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20  threadsafe, but 
cc60: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
cc70: 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54  ().** is not.  T
cc80: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
cc90: 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20  own() interface 
cca0: 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c  must only be cal
ccb0: 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69  led from a.** si
ccc0: 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c  ngle thread.  Al
ccd0: 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  l open [database
cce0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75   connections] mu
ccf0: 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64  st be closed and
cd00: 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51   all.** other SQ
cd10: 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d  Lite resources m
cd20: 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  ust be deallocat
cd30: 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f  ed prior to invo
cd40: 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  king.** sqlite3_
cd50: 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a  shutdown()..**.*
cd60: 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68  * Among other th
cd70: 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69  ings, ^sqlite3_i
cd80: 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c  nitialize() will
cd90: 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
cda0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53  e3_os_init().  S
cdb0: 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74  imilarly, ^sqlit
cdc0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a  e3_shutdown().**
cdd0: 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c   will invoke sql
cde0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a  ite3_os_end()..*
cdf0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
ce00: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
ce10: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b  outine returns [
ce20: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
ce30: 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f  ccess..** ^If fo
ce40: 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73  r some reason, s
ce50: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
ce60: 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  e() is unable to
ce70: 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74   initialize.** t
ce80: 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68  he library (perh
ce90: 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65  aps it is unable
cea0: 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e   to allocate a n
ceb0: 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73  eeded resource s
cec0: 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65  uch.** as a mute
ced0: 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e  x) it returns an
cee0: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74   [error code] ot
cef0: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
cf00: 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _OK]..**.** ^The
cf10: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
cf20: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ize() routine is
cf30: 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c   called internal
cf40: 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72  ly by many other
cf50: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
cf60: 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e  faces so that an
cf70: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75   application usu
cf80: 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65  ally does not ne
cf90: 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20  ed to.** invoke 
cfa0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
cfb0: 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  ze() directly.  
cfc0: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71  For example, [sq
cfd0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
cfe0: 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69   calls sqlite3_i
cff0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74  nitialize() so t
d000: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
d010: 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  y will be automa
d020: 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69  tically.** initi
d030: 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c  alized when [sql
d040: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20  ite3_open()] is 
d050: 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73  called if it has
d060: 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69   not be initiali
d070: 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20  zed.** already. 
d080: 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51   ^However, if SQ
d090: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
d0a0: 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
d0b0: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
d0c0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
d0d0: 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68   option, then th
d0e0: 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c  e automatic call
d0f0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  s to sqlite3_ini
d100: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65  tialize().** are
d110: 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65   omitted and the
d120: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
d130: 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69  t call sqlite3_i
d140: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
d150: 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  ctly.** prior to
d160: 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
d170: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
d180: 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20  e.  For maximum 
d190: 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20  portability,.** 
d1a0: 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
d1b0: 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
d1c0: 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b  ons always invok
d1d0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
d1e0: 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74  lize().** direct
d1f0: 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ly prior to usin
d200: 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
d210: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
d220: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a  uture releases.*
d230: 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  * of SQLite may 
d240: 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49  require this.  I
d250: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
d260: 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69  he behavior exhi
d270: 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51  bited.** when SQ
d280: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
d290: 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d   with [SQLITE_OM
d2a0: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67  IT_AUTOINIT] mig
d2b0: 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a  ht become the.**
d2c0: 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
d2d0: 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65  r in some future
d2e0: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
d2f0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te..**.** The sq
d300: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
d310: 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65  routine does ope
d320: 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
d330: 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61  ecific.** initia
d340: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  lization of the 
d350: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
d360: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
d370: 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  end().** routine
d380: 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65   undoes the effe
d390: 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  ct of sqlite3_os
d3a0: 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61  _init().  Typica
d3b0: 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f  l tasks.** perfo
d3c0: 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f  rmed by these ro
d3d0: 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61  utines include a
d3e0: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61  llocation or dea
d3f0: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
d400: 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73  static resources
d410: 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  , initialization
d420: 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61   of global varia
d430: 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67  bles,.** setting
d440: 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73   up a default [s
d450: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75  qlite3_vfs] modu
d460: 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75  le, or setting u
d470: 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63  p.** a default c
d480: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69  onfiguration usi
d490: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ng [sqlite3_conf
d4a0: 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ig()]..**.** The
d4b0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
d4c0: 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  uld never invoke
d4d0: 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f   either sqlite3_
d4e0: 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20  os_init().** or 
d4f0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
d500: 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20   directly.  The 
d510: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
d520: 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a  ld only invoke.*
d530: 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  * sqlite3_initia
d540: 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lize() and sqlit
d550: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
d560: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
d570: 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  nit().** interfa
d580: 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74  ce is called aut
d590: 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
d5a0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
d5b0: 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  () and.** sqlite
d5c0: 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61  3_os_end() is ca
d5d0: 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  lled by sqlite3_
d5e0: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70  shutdown().  App
d5f0: 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c  ropriate.** impl
d600: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20  ementations for 
d610: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
d620: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
d630: 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75  _end().** are bu
d640: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20  ilt into SQLite 
d650: 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69  when it is compi
d660: 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69  led for Unix, Wi
d670: 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a  ndows, or OS/2..
d680: 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20  ** When [custom 
d690: 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66  builds | built f
d6a0: 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72  or other platfor
d6b0: 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68  ms].** (using th
d6c0: 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48  e [SQLITE_OS_OTH
d6d0: 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ER=1] compile-ti
d6e0: 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68  me.** option) th
d6f0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
d700: 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74  st supply a suit
d710: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
d720: 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  ion for.** sqlit
d730: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
d740: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
d750: 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69  ).  An applicati
d760: 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69  on-supplied.** i
d770: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
d780: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
d790: 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  () or sqlite3_os
d7a0: 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72  _end().** must r
d7b0: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
d7c0: 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64  ] on success and
d7d0: 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72   some other [err
d7e0: 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a  or code] upon.**
d7f0: 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74   failure..*/.int
d800: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
d810: 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  ize(void);.int s
d820: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
d830: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
d840: 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29  e3_os_init(void)
d850: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  ;.int sqlite3_os
d860: 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  _end(void);../*.
d870: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
d880: 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c  figuring The SQL
d890: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
d8a0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
d8b0: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
d8c0: 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
d8d0: 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72   global configur
d8e0: 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
d8f0: 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   to SQLite in or
d900: 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69  der to tune SQLi
d910: 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  te to the specif
d920: 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74  ic needs of.** t
d930: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
d940: 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e   The default con
d950: 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65  figuration is re
d960: 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f  commended for mo
d970: 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  st.** applicatio
d980: 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72  ns and so this r
d990: 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c  outine is usuall
d9a0: 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e  y not necessary.
d9b0: 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69    It is.** provi
d9c0: 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72  ded to support r
d9d0: 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  are applications
d9e0: 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65   with unusual ne
d9f0: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  eds..**.** The s
da00: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
da10: 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
da20: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
da30: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
da40: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
da50: 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  t no other SQLit
da60: 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
da70: 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65   invoked by othe
da80: 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69  r.** threads whi
da90: 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  le sqlite3_confi
daa0: 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  g() is running. 
dab0: 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71   Furthermore, sq
dac0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a  lite3_config().*
dad0: 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e  * may only be in
dae0: 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c  voked prior to l
daf0: 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a  ibrary initializ
db00: 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
db10: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
db20: 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73  ze()] or after s
db30: 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69  hutdown by [sqli
db40: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e  te3_shutdown()].
db50: 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
db60: 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c  config() is call
db70: 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
db80: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
db90: 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73  and before.** [s
dba0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
dbb0: 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20  )] then it will 
dbc0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49  return SQLITE_MI
dbd0: 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68  SUSE..** Note, h
dbe0: 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71  owever, that ^sq
dbf0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63  lite3_config() c
dc00: 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20  an be called as 
dc10: 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69  part of the.** i
dc20: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
dc30: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
dc40: 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33  defined [sqlite3
dc50: 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a  _os_init()]..**.
dc60: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
dc70: 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
dc80: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20  _config() is an 
dc90: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66  integer.** [conf
dca0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
dcb0: 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  ] that determine
dcc0: 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72  s.** what proper
dcd0: 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20  ty of SQLite is 
dce0: 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64  to be configured
dcf0: 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  .  Subsequent ar
dd00: 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20  guments.** vary 
dd10: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
dd20: 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
dd30: 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  option].** in th
dd40: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
dd50: 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20  ..**.** ^When a 
dd60: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
dd70: 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c  tion is set, sql
dd80: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65  ite3_config() re
dd90: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
dda0: 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70  ]..** ^If the op
ddb0: 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20  tion is unknown 
ddc0: 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  or SQLite is una
ddd0: 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f  ble to set the o
dde0: 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68  ption.** then th
ddf0: 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
de00: 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  ns a non-zero [e
de10: 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69  rror code]..*/.i
de20: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  nt sqlite3_confi
de30: 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  g(int, ...);../*
de40: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
de50: 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65  nfigure database
de60: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a   connections.**.
de70: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64  ** The sqlite3_d
de80: 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
de90: 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
dea0: 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69  make configurati
deb0: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
dec0: 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
ded0: 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69  nection].  The i
dee0: 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69  nterface is simi
def0: 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lar to.** [sqlit
df00: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63  e3_config()] exc
df10: 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61  ept that the cha
df20: 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20  nges apply to a 
df30: 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62  single.** [datab
df40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
df50: 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68  (specified in th
df60: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
df70: 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  )..**.** The sec
df80: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
df90: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
dfa0: 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74  g(D,V,...)  is t
dfb0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42  he.** [SQLITE_DB
dfc0: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
dfd0: 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
dfe0: 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65   verb] - an inte
dff0: 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61  ger code .** tha
e000: 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74  t indicates what
e010: 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b   aspect of the [
e020: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
e030: 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f  ion] is being co
e040: 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62  nfigured..** Sub
e050: 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
e060: 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  s vary depending
e070: 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72   on the configur
e080: 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a  ation verb..**.*
e090: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
e0a0: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
e0b0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
e0c0: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
e0d0: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63  ** the call is c
e0e0: 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73  onsidered succes
e0f0: 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  sful..*/.int sql
e100: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73  ite3_db_config(s
e110: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c  qlite3*, int op,
e120: 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
e130: 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
e140: 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e  llocation Routin
e150: 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  es.**.** An inst
e160: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
e170: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
e180: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
e190: 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  n SQLite.** and 
e1a0: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
e1b0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
e1c0: 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ines..**.** This
e1d0: 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20   object is used 
e1e0: 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63  in only one plac
e1f0: 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
e200: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20  interface..** A 
e210: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
e220: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
e230: 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67  bject is the arg
e240: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c  ument to.** [sql
e250: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
e260: 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72  hen the configur
e270: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a  ation option is.
e280: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
e290: 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51  G_MALLOC] or [SQ
e2a0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
e2b0: 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20  ALLOC].  .** By 
e2c0: 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74  creating an inst
e2d0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
e2e0: 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69  ect.** and passi
e2f0: 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
e300: 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
e310: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
e320: 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66  ).** during conf
e330: 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70  iguration, an ap
e340: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70  plication can sp
e350: 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
e360: 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
e370: 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
e380: 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74  tem for SQLite t
e390: 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  o use for all of
e3a0: 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20   its.** dynamic 
e3b0: 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a  memory needs..**
e3c0: 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
e3d0: 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20  Lite comes with 
e3e0: 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69  several [built-i
e3f0: 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
e400: 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65  ors].** that are
e410: 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75   perfectly adequ
e420: 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72  ate for the over
e430: 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74  whelming majorit
e440: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
e450: 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68  s.** and that th
e460: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c  is object is onl
e470: 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69  y useful to a ti
e480: 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61  ny minority of a
e490: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77  pplications.** w
e4a0: 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ith specialized 
e4b0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
e4c0: 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20  n requirements. 
e4d0: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a   This object is.
e4e0: 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72  ** also used dur
e4f0: 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53  ing testing of S
e500: 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
e510: 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  o specify an alt
e520: 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
e530: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
e540: 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f  t simulates memo
e550: 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  ry out-of-memory
e560: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a   conditions in.*
e570: 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66  * order to verif
e580: 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65  y that SQLite re
e590: 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c  covers gracefull
e5a0: 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63  y from such.** c
e5b0: 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  onditions..**.**
e5c0: 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52   The xMalloc, xR
e5d0: 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65  ealloc, and xFre
e5e0: 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77  e methods must w
e5f0: 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20  ork like the.** 
e600: 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f  malloc(), reallo
e610: 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
e620: 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68  unctions from th
e630: 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
e640: 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  rary..** ^SQLite
e650: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
e660: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
e670: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c  ment to.** xReal
e680: 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20  loc is always a 
e690: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
e6a0: 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
e6b0: 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a  o xRoundup..**.*
e6c0: 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72  * xSize should r
e6d0: 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61  eturn the alloca
e6e0: 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65  ted size of a me
e6f0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
e700: 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  ** previously ob
e710: 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c  tained from xMal
e720: 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e  loc or xRealloc.
e730: 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20    The allocated 
e740: 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79  size.** is alway
e750: 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69  s at least as bi
e760: 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74  g as the request
e770: 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20  ed size but may 
e780: 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a  be larger..**.**
e790: 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65   The xRoundup me
e7a0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61  thod returns wha
e7b0: 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61  t would be the a
e7c0: 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
e7d0: 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  .** a memory all
e7e0: 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20  ocation given a 
e7f0: 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65  particular reque
e800: 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74  sted size.  Most
e810: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
e820: 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d  ators round up m
e830: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
e840: 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68  s at least to th
e850: 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a  e next multiple.
e860: 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61  ** of 8.  Some a
e870: 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
e880: 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d  up to a larger m
e890: 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20  ultiple or to a 
e8a0: 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45  power of 2..** E
e8b0: 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  very memory allo
e8c0: 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63  cation request c
e8d0: 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68  oming in through
e8e0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
e8f0: 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
e900: 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69  e3_realloc()] fi
e910: 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64  rst calls xRound
e920: 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70  up.  If xRoundup
e930: 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20   returns 0, .** 
e940: 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20  that causes the 
e950: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65  corresponding me
e960: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
e970: 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54  to fail..**.** T
e980: 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
e990: 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20  initializes the 
e9a0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
e9b0: 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .  (For example,
e9c0: 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c  .** it might all
e9d0: 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72  ocate any requir
e9e0: 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69  e mutexes or ini
e9f0: 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c  tialize internal
ea00: 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75   data.** structu
ea10: 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64  res.  The xShutd
ea20: 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  own method is in
ea30: 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c  voked (indirectl
ea40: 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  y) by.** [sqlite
ea50: 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e  3_shutdown()] an
ea60: 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63  d should dealloc
ea70: 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65  ate any resource
ea80: 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79  s acquired.** by
ea90: 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70   xInit.  The pAp
eaa0: 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73  pData pointer is
eab0: 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c   used as the onl
eac0: 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  y parameter to.*
ead0: 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75  * xInit and xShu
eae0: 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  tdown..**.** SQL
eaf0: 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53  ite holds the [S
eb00: 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
eb10: 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78  IC_MASTER] mutex
eb20: 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73   when it invokes
eb30: 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65  .** the xInit me
eb40: 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e  thod, so the xIn
eb50: 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e  it method need n
eb60: 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  ot be threadsafe
eb70: 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64  .  The.** xShutd
eb80: 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e  own method is on
eb90: 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b  ly called from [
eba0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
ebb0: 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a  ()] so it does.*
ebc0: 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  * not need to be
ebd0: 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68   threadsafe eith
ebe0: 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68  er.  For all oth
ebf0: 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69  er methods, SQLi
ec00: 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20  te.** holds the 
ec10: 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
ec20: 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20  ATIC_MEM] mutex 
ec30: 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a  as long as the.*
ec40: 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
ec50: 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66  _MEMSTATUS] conf
ec60: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
ec70: 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77   is turned on (w
ec80: 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79  hich.** it is by
ec90: 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f   default) and so
eca0: 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65   the methods are
ecb0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73   automatically s
ecc0: 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f  erialized..** Ho
ecd0: 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54  wever, if [SQLIT
ece0: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
ecf0: 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c  US] is disabled,
ed00: 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a   then the other.
ed10: 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ** methods must 
ed20: 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72  be threadsafe or
ed30: 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72   else make their
ed40: 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74   own arrangement
ed50: 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69  s for.** seriali
ed60: 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  zation..**.** SQ
ed70: 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
ed80: 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d  invoke xInit() m
ed90: 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69  ore than once wi
eda0: 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65  thout an interve
edb0: 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  ning.** call to 
edc0: 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a  xShutdown()..*/.
edd0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
ede0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
edf0: 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ds sqlite3_mem_m
ee00: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
ee10: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
ee20: 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ds {.  void *(*x
ee30: 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20  Malloc)(int);   
ee40: 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20        /* Memory 
ee50: 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74  allocation funct
ee60: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  ion */.  void (*
ee70: 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20  xFree)(void*);  
ee80: 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20          /* Free 
ee90: 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  a prior allocati
eea0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a  on */.  void *(*
eeb0: 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c  xRealloc)(void*,
eec0: 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65  int);  /* Resize
eed0: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
eee0: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29  /.  int (*xSize)
eef0: 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
ef00: 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65     /* Return the
ef10: 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f   size of an allo
ef20: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
ef30: 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29  (*xRoundup)(int)
ef40: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f  ;          /* Ro
ef50: 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73  und up request s
ef60: 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f  ize to allocatio
ef70: 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20  n size */.  int 
ef80: 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b  (*xInit)(void*);
ef90: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e             /* In
efa0: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
efb0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
efc0: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64  .  void (*xShutd
efd0: 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  own)(void*);    
efe0: 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a    /* Deinitializ
eff0: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
f000: 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
f010: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
f020: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72             /* Ar
f030: 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28  gument to xInit(
f040: 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28  ) and xShutdown(
f050: 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ) */.};../*.** C
f060: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
f070: 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
f080: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e  * KEYWORDS: {con
f090: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
f0a0: 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  n}.**.** These c
f0b0: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
f0c0: 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
f0d0: 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
f0e0: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
f0f0: 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
f100: 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
f110: 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
f120: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
f130: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
f140: 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
f150: 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
f160: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
f170: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
f180: 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
f190: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
f1a0: 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
f1b0: 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
f1c0: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
f1d0: 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
f1e0: 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
f1f0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
f200: 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
f210: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
f220: 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b  l worked.  The [
f230: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
f240: 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
f250: 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
f260: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
f270: 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
f280: 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
f290: 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
f2a0: 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
f2b0: 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
f2c0: 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  l>.** [[SQLITE_C
f2d0: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
f2e0: 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
f2f0: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
f300: 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
f310: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
f320: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
f330: 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
f340: 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
f350: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
f360: 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65  ] to Single-thre
f370: 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
f380: 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
f390: 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67  .** all mutexing
f3a0: 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65   and puts SQLite
f3b0: 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65   into a mode whe
f3c0: 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62  re it can only b
f3d0: 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73  e used.** by a s
f3e0: 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20  ingle thread.   
f3f0: 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
f400: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
f410: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
f420: 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
f430: 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
f440: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
f450: 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
f460: 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63  ot possible to c
f470: 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61  hange the [threa
f480: 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20  ding mode] from 
f490: 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76  its default.** v
f4a0: 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74  alue of Single-t
f4b0: 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71  hread and so [sq
f4c0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
f4d0: 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20  will return .** 
f4e0: 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
f4f0: 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
f500: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
f510: 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20  SINGLETHREAD.** 
f520: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
f530: 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
f540: 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
f550: 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c  _MULTITHREAD]] <
f560: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
f570: 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74  _MULTITHREAD</dt
f580: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
f590: 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
f5a0: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
f5b0: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
f5c0: 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
f5d0: 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75  ding mode] to Mu
f5e0: 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  lti-thread.  In 
f5f0: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
f600: 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65  disables.** mute
f610: 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73  xing on [databas
f620: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
f630: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
f640: 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
f650: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
f660: 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  on is responsibl
f670: 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e  e for serializin
f680: 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b  g access to.** [
f690: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
f6a0: 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
f6b0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e  red statements].
f6c0: 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65    But other mute
f6d0: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
f6e0: 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74  ed so that SQLit
f6f0: 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74  e will be safe t
f700: 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69  o use in a multi
f710: 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76  -threaded.** env
f720: 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67  ironment as long
f730: 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61   as no two threa
f740: 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ds attempt to us
f750: 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64  e the same.** [d
f760: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
f770: 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20  on] at the same 
f780: 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74  time.  ^If SQLit
f790: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
f7a0: 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
f7b0: 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
f7c0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
f7d0: 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
f7e0: 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
f7f0: 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
f800: 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75  le to set the Mu
f810: 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
f820: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
f830: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
f840: 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
f850: 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
f860: 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
f870: 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
f880: 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
f890: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
f8a0: 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
f8b0: 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
f8c0: 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c  G_SERIALIZED]] <
f8d0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
f8e0: 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e  _SERIALIZED</dt>
f8f0: 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
f900: 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
f910: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
f920: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
f930: 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
f940: 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72  ing mode] to Ser
f950: 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65  ialized. In othe
f960: 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70  r words, this op
f970: 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20  tion enables.** 
f980: 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c  all mutexes incl
f990: 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73  uding the recurs
f9a0: 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f  ive.** mutexes o
f9b0: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
f9c0: 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
f9d0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
f9e0: 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20   objects..** In 
f9f0: 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68  this mode (which
fa00: 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20   is the default 
fa10: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
fa20: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
fa30: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
fa40: 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74  FE=1]) the SQLit
fa50: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69  e library will i
fa60: 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20  tself serialize 
fa70: 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61  access.** to [da
fa80: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
fa90: 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
faa0: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f  d statements] so
fab0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70   that the.** app
fac0: 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  lication is free
fad0: 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
fae0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
faf0: 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a  ction] or the.**
fb00: 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
fb10: 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69  statement] in di
fb20: 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20  fferent threads 
fb30: 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
fb40: 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20  ..** ^If SQLite 
fb50: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
fb60: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
fb70: 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
fb80: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
fb90: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
fba0: 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
fbb0: 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
fbc0: 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69   to set the Seri
fbd0: 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
fbe0: 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
fbf0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
fc00: 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
fc10: 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
fc20: 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
fc30: 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
fc40: 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66  _SERIALIZED conf
fc50: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
fc60: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
fc70: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
fc80: 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOC]] <dt>SQLITE
fc90: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f  _CONFIG_MALLOC</
fca0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
fcb0: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
fcc0: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
fcd0: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
fce0: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
fcf0: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
fd00: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
fd10: 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
fd20: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
fd30: 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e  cifies.** altern
fd40: 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
fd50: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
fd60: 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  n routines to be
fd70: 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f   used in place o
fd80: 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20  f.** the memory 
fd90: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
fda0: 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
fdb0: 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65  QLite.)^ ^SQLite
fdc0: 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77   makes.** its ow
fdd0: 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
fde0: 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  f the content of
fdf0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
fe00: 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
fe10: 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74  ture.** before t
fe20: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
fe30: 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72  ig()] call retur
fe40: 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ns.</dd>.**.** [
fe50: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
fe60: 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  ETMALLOC]] <dt>S
fe70: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
fe80: 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
fe90: 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
fea0: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
feb0: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
fec0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
fed0: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
fee0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
fef0: 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
ff00: 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c  cture.  The [sql
ff10: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
ff20: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
ff30: 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
ff40: 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
ff50: 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ned memory alloc
ff60: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29  ation routines.)
ff70: 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
ff80: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
ff90: 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
ffa0: 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
ffb0: 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
ffc0: 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
ffd0: 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f  r that simulatio
ffe0: 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ns memory alloca
fff0: 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a  tion failure or.
10000 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79  ** tracks memory
10010 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d   usage, for exam
10020 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ple. </dd>.**.**
10030 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
10040 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74  _MEMSTATUS]] <dt
10050 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
10060 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a  EMSTATUS</dt>.**
10070 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
10080 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20  on takes single 
10090 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65  argument of type
100a0 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65   int, interprete
100b0 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65  d as a .** boole
100c0 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65  an, which enable
100d0 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
100e0 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20  e collection of 
100f0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10100 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73  n .** statistics
10110 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20  . ^(When memory 
10120 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
10130 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c  stics are disabl
10140 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c  ed, the .** foll
10150 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74  owing SQLite int
10160 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e  erfaces become n
10170 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a  on-operational:.
10180 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  **   <ul>.**   <
10190 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
101a0 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20  ory_used()].**  
101b0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
101c0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
101d0 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
101e0 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
101f0 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20  limit64()].**   
10200 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74  <li> [sqlite3_st
10210 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75  atus()].**   </u
10220 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20  l>)^.** ^Memory 
10230 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
10240 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65  stics are enable
10250 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c  d by default unl
10260 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  ess SQLite is.**
10270 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b   compiled with [
10280 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d  SQLITE_DEFAULT_M
10290 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77  EMSTATUS]=0 in w
102a0 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79  hich case memory
102b0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  .** allocation s
102c0 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69  tatistics are di
102d0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
102e0 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  t..** </dd>.**.*
102f0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
10300 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e  G_SCRATCH]] <dt>
10310 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
10320 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RATCH</dt>.** <d
10330 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
10340 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
10350 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
10360 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
10370 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61   use for.** scra
10380 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65  tch memory.  The
10390 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
103a0 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74  uments:  A point
103b0 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  er an 8-byte.** 
103c0 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62  aligned memory b
103d0 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68  uffer from which
103e0 20 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c   the scratch all
103f0 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65  ocations will be
10400 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73  .** drawn, the s
10410 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61  ize of each scra
10420 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28  tch allocation (
10430 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20  sz),.** and the 
10440 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
10450 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  f scratch alloca
10460 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20  tions (N).  The 
10470 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d  sz.** argument m
10480 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c  ust be a multipl
10490 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20  e of 16..** The 
104a0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
104b0 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72  ust be a pointer
104c0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c   to an 8-byte al
104d0 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20  igned buffer.** 
104e0 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
104f0 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
10500 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
10510 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68  l use no more th
10520 61 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20 62  an two scratch b
10530 75 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61  uffers per threa
10540 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75  d.  So.** N shou
10550 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 77 69  ld be set to twi
10560 63 65 20 74 68 65 20 65 78 70 65 63 74 65 64 20  ce the expected 
10570 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
10580 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53  f threads..** ^S
10590 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
105a0 20 72 65 71 75 69 72 65 20 61 20 73 63 72 61 74   require a scrat
105b0 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69  ch buffer that i
105c0 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a  s more than 6.**
105d0 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62   times the datab
105e0 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20 5e  ase page size. ^
105f0 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20  If SQLite needs 
10600 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c  needs additional
10610 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  .** scratch memo
10620 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69  ry beyond what i
10630 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
10640 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
10650 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a   option, then .*
10660 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
10670 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65  c()] will be use
10680 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20  d to obtain the 
10690 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f  memory needed.</
106a0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
106b0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
106c0 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  CHE]] <dt>SQLITE
106d0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
106e0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
106f0 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
10700 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
10710 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
10720 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
10730 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61   for.** the data
10740 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20  base page cache 
10750 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74  with the default
10760 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
10770 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a  ementation.  .**
10780 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74   This configurat
10790 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  ion should not b
107a0 65 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 70  e used if an app
107b0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20  lication-define 
107c0 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d  page.** cache im
107d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
107e0 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65  loaded using the
107f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
10800 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a  CACHE2 option..*
10810 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65  * There are thre
10820 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  e arguments to t
10830 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f  his option: A po
10840 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20  inter to 8-byte 
10850 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72  aligned.** memor
10860 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  y, the size of e
10870 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20  ach page buffer 
10880 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75  (sz), and the nu
10890 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e  mber of pages (N
108a0 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67  )..** The sz arg
108b0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
108c0 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
108d0 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65  largest database
108e0 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65   page.** (a powe
108f0 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e  r of two between
10900 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 29 20   512 and 32768) 
10910 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78  plus a little ex
10920 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  tra for each.** 
10930 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54  page header.  ^T
10940 68 65 20 70 61 67 65 20 68 65 61 64 65 72 20 73  he page header s
10950 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30 20  ize is 20 to 40 
10960 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20  bytes depending 
10970 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61  on.** the host a
10980 72 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49  rchitecture.  ^I
10990 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61  t is harmless, a
109a0 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61  part from the wa
109b0 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20  sted memory,.** 
109c0 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74  to make sz a lit
109d0 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20  tle too large.  
109e0 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67  The first.** arg
109f0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69  ument should poi
10a00 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74  nt to an allocat
10a10 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ion of at least 
10a20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
10a30 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  mory..** ^SQLite
10a40 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65   will use the me
10a50 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79  mory provided by
10a60 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
10a70 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69  ent to satisfy i
10a80 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65  ts.** memory nee
10a90 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  ds for the first
10aa0 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74   N pages that it
10ab0 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20   adds to cache. 
10ac0 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a   ^If additional.
10ad0 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65  ** page cache me
10ae0 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62  mory is needed b
10af0 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
10b00 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f  ovided by this o
10b10 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53  ption, then.** S
10b20 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73  QLite goes to [s
10b30 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
10b40 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f   for the additio
10b50 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63  nal storage spac
10b60 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  e..** The pointe
10b70 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  r in the first a
10b80 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20  rgument must.** 
10b90 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
10ba0 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8-byte boundary
10bb0 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62   or subsequent b
10bc0 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
10bd0 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64  e.** will be und
10be0 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a  efined.</dd>.**.
10bf0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
10c00 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51  IG_HEAP]] <dt>SQ
10c10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
10c20 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
10c30 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
10c40 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
10c50 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
10c60 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
10c70 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  .** for all of i
10c80 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ts dynamic memor
10c90 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
10ca0 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20  ds beyond those 
10cb0 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20  provided.** for 
10cc0 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  by [SQLITE_CONFI
10cd0 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b  G_SCRATCH] and [
10ce0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
10cf0 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65  GECACHE]..** The
10d00 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
10d10 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74  uments: An 8-byt
10d20 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65  e aligned pointe
10d30 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c  r to the memory,
10d40 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
10d50 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d  f bytes in the m
10d60 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e  emory buffer, an
10d70 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  d the minimum al
10d80 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a  location size..*
10d90 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20  * ^If the first 
10da0 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
10db0 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20  ory pointer) is 
10dc0 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74  NULL, then SQLit
10dd0 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20  e reverts.** to 
10de0 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c  using its defaul
10df0 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
10e00 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d  or (the system m
10e10 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e  alloc() implemen
10e20 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f  tation),.** undo
10e30 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e  ing any prior in
10e40 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c  vocation of [SQL
10e50 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
10e60 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  C].  ^If the.** 
10e70 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69  memory pointer i
10e80 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65  s not NULL and e
10e90 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e  ither [SQLITE_EN
10ea0 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72  ABLE_MEMSYS3] or
10eb0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
10ec0 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20  LE_MEMSYS5] are 
10ed0 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68  defined, then th
10ee0 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65  e alternative me
10ef0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
10f00 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20  r is engaged to 
10f10 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51  handle all of SQ
10f20 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  Lites memory all
10f30 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a  ocation needs..*
10f40 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e  * The first poin
10f50 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
10f60 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65  pointer) must be
10f70 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
10f80 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72  -byte.** boundar
10f90 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  y or subsequent 
10fa0 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
10fb0 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66  te will be undef
10fc0 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e  ined..** The min
10fd0 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
10fe0 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61  size is capped a
10ff0 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61  t 2**12. Reasona
11000 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f  ble values.** fo
11010 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  r the minimum al
11020 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72  location size ar
11030 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32  e 2**5 through 2
11040 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  **8.</dd>.**.** 
11050 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
11060 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
11070 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c  TE_CONFIG_MUTEX<
11080 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
11090 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
110a0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
110b0 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
110c0 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
110d0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
110e0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
110f0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
11100 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
11110 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74  specifies.** alt
11120 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
11130 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  el mutex routine
11140 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20  s to be used in 
11150 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74  place.** the mut
11160 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c  ex routines buil
11170 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e  t into SQLite.)^
11180 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20    ^SQLite makes 
11190 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
111a0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
111b0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
111c0 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
111d0 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c  e before the cal
111e0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
111f0 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72  _config()] retur
11200 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69  ns. ^If SQLite i
11210 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
11220 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
11230 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
11240 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
11250 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
11260 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65  tion then.** the
11270 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67   entire mutexing
11280 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d   subsystem is om
11290 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62  itted from the b
112a0 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63  uild and hence c
112b0 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
112c0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
112d0 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
112e0 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69  NFIG_MUTEX confi
112f0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
11300 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
11310 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
11320 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
11330 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
11340 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  EX]] <dt>SQLITE_
11350 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c  CONFIG_GETMUTEX<
11360 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
11370 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
11380 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
11390 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
113a0 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
113b0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
113c0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
113d0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
113e0 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
113f0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
11400 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
11410 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
11420 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
11430 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  ned mutex routin
11440 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
11450 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
11460 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
11470 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61   default mutex a
11480 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
11490 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
114a0 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61  pper used to tra
114b0 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66  ck mutex usage f
114c0 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a  or performance.*
114d0 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74  * profiling or t
114e0 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d  esting, for exam
114f0 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ple.   ^If SQLit
11500 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
11510 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
11520 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
11530 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
11540 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
11550 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
11560 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
11570 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
11580 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
11590 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
115a0 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
115b0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
115c0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
115d0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
115e0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
115f0 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
11600 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
11610 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
11620 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
11630 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e  LOOKASIDE]] <dt>
11640 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
11650 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
11660 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
11670 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
11680 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
11690 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c  rmine the defaul
116a0 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t.** memory allo
116b0 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c  cation for the l
116c0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
116d0 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63  allocator on eac
116e0 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
116f0 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
11700 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
11710 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
11720 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
11730 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64   buffer slot and
11740 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74   the second is t
11750 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
11760 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20  slots allocated 
11770 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
11780 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20   connection.)^  
11790 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65  ^(This option se
117a0 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66  ts the.** <i>def
117b0 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69  ault</i> lookasi
117c0 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51  de size. The [SQ
117d0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
117e0 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62  OKASIDE].** verb
117f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
11800 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65  config()] can be
11810 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20   used to change 
11820 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  the lookaside.**
11830 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
11840 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e  n individual con
11850 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64  nections.)^ </dd
11860 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
11870 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d  _CONFIG_PCACHE2]
11880 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
11890 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e  FIG_PCACHE2</dt>
118a0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
118b0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
118c0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
118d0 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
118e0 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69  r to.** an [sqli
118f0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
11900 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  ds2] object.  Th
11910 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  is object specif
11920 69 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ies the interfac
11930 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d  e.** to a custom
11940 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
11950 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e  ementation.)^  ^
11960 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
11970 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62  opy of the.** ob
11980 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20 69 74  ject and uses it
11990 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20   for page cache 
119a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
119b0 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ns.</dd>.**.** [
119c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
119d0 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e  ETPCACHE2]] <dt>
119e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
119f0 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a  TPCACHE2</dt>.**
11a00 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
11a10 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
11a20 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
11a30 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
11a40 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  o an.** [sqlite3
11a50 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
11a60 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74  ] object.  SQLit
11a70 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65 20  e copies of the 
11a80 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20  current.** page 
11a90 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
11aa0 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f  tion into that o
11ab0 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a  bject.)^ </dd>.*
11ac0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
11ad0 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53  NFIG_LOG]] <dt>S
11ae0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
11af0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
11b00 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
11b10 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _LOG option take
11b20 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a  s two arguments:
11b30 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a   a pointer to a.
11b40 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  ** function with
11b50 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72   a call signatur
11b60 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69  e of void(*)(voi
11b70 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
11b80 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70  r*), .** and a p
11b90 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20  ointer to void. 
11ba0 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
11bb0 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
11bc0 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69  NULL, it is.** i
11bd0 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74  nvoked by [sqlit
11be0 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f  e3_log()] to pro
11bf0 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e  cess each loggin
11c00 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
11c10 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f  e.** function po
11c20 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74  inter is NULL, t
11c30 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  he [sqlite3_log(
11c40 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63  )] interface bec
11c50 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a  omes a no-op..**
11c60 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74   ^The void point
11c70 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73  er that is the s
11c80 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
11c90 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
11ca0 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64  LOG is.** passed
11cb0 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
11cc0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
11cd0 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
11ce0 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
11cf0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68  r.** function wh
11d00 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63  enever that func
11d10 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e  tion is invoked.
11d20 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61    ^The second pa
11d30 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
11d40 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
11d50 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  n is a copy of t
11d60 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
11d70 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73  er to the corres
11d80 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  ponding.** [sqli
11d90 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20  te3_log()] call 
11da0 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20  and is intended 
11db0 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20  to be a [result 
11dc0 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b  code] or an.** [
11dd0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
11de0 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69  code].  ^The thi
11df0 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73  rd parameter pas
11e00 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65  sed to the logge
11e10 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73  r is.** log mess
11e20 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74  age after format
11e30 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65  ting via [sqlite
11e40 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a  3_snprintf()]..*
11e50 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67  * The SQLite log
11e60 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69  ging interface i
11e70 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b  s not reentrant;
11e80 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
11e90 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64  tion.** supplied
11ea0 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
11eb0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76  ion must not inv
11ec0 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  oke any SQLite i
11ed0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20  nterface..** In 
11ee0 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
11ef0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68   application, th
11f00 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
11f10 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
11f20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  function must be
11f30 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64   threadsafe. </d
11f40 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
11f50 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c  E_CONFIG_URI]] <
11f60 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
11f70 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54 68 69  _URI.** <dd> Thi
11f80 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
11f90 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
11fa0 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66   of type int. If
11fb0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a   non-zero, then.
11fc0 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  ** URI handling 
11fd0 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62  is globally enab
11fe0 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61  led. If the para
11ff0 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74  meter is zero, t
12000 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  hen URI handling
12010 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  .** is globally 
12020 64 69 73 61 62 6c 65 64 2e 20 49 66 20 55 52 49  disabled. If URI
12030 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
12040 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20 61  bally enabled, a
12050 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20  ll filenames.** 
12060 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74  passed to [sqlit
12070 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
12080 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
12090 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
120a0 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66  ()] or.** specif
120b0 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b  ied as part of [
120c0 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73  ATTACH] commands
120d0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
120e0 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64   as URIs, regard
120f0 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68  less.** of wheth
12100 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53  er or not the [S
12110 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
12120 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e  flag is set when
12130 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
12140 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
12150 70 65 6e 65 64 2e 20 49 66 20 69 74 20 69 73 20  pened. If it is 
12160 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65  globally disable
12170 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65  d, filenames are
12180 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72  .** only interpr
12190 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20  eted as URIs if 
121a0 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
121b0 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20  URI flag is set 
121c0 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61  when the.** data
121d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
121e0 69 73 20 6f 70 65 6e 65 64 2e 20 42 79 20 64 65  is opened. By de
121f0 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c  fault, URI handl
12200 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a  ing is globally.
12210 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65  ** disabled. The
12220 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d   default value m
12230 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79  ay be changed by
12240 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20   compiling with 
12250 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  the.** [SQLITE_U
12260 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64  SE_URI] symbol d
12270 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  efined..**.** [[
12280 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
12290 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f  ACHE]] [[SQLITE_
122a0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
122b0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
122c0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61  _CONFIG_PCACHE a
122d0 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 4e 49  nd SQLITE_CONFNI
122e0 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c  G_GETPCACHE.** <
122f0 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e  dd> These option
12300 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61  s are obsolete a
12310 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  nd should not be
12320 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64   used by new cod
12330 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72  e..** They are r
12340 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b  etained for back
12350 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
12360 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20  ity but are now 
12370 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e  no-ops..** </dl>
12380 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
12390 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
123a0 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69  THREAD  1  /* ni
123b0 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
123c0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
123d0 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e  THREAD   2  /* n
123e0 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
123f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
12400 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20  ALIZED    3  /* 
12410 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
12420 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
12430 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a  LOC        4  /*
12440 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
12450 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
12460 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
12470 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20  ETMALLOC     5  
12480 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
12490 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
124a0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
124b0 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36  _SCRATCH       6
124c0 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
124d0 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
124e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
124f0 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20  IG_PAGECACHE    
12500 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   7  /* void*, in
12510 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23  t sz, int N */.#
12520 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
12530 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20  NFIG_HEAP       
12540 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     8  /* void*, 
12550 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d  int nByte, int m
12560 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  in */.#define SQ
12570 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
12580 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20  TATUS     9  /* 
12590 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69  boolean */.#defi
125a0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
125b0 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30  _MUTEX        10
125c0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
125d0 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  ex_methods* */.#
125e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
125f0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20  NFIG_GETMUTEX   
12600 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33    11  /* sqlite3
12610 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
12620 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79  */./* previously
12630 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43   SQLITE_CONFIG_C
12640 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69  HUNKALLOC 12 whi
12650 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64  ch is now unused
12660 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51  . */ .#define SQ
12670 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
12680 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20  ASIDE    13  /* 
12690 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69  int int */.#defi
126a0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
126b0 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34  _PCACHE       14
126c0 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
126d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
126e0 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20  FIG_GETPCACHE   
126f0 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f   15  /* no-op */
12700 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
12710 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20  CONFIG_LOG      
12720 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63      16  /* xFunc
12730 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69  , void* */.#defi
12740 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
12750 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37  _URI          17
12760 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66    /* int */.#def
12770 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
12780 47 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 31  G_PCACHE2      1
12790 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63  8  /* sqlite3_pc
127a0 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a  ache_methods2* *
127b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
127c0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
127d0 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69  E2   19  /* sqli
127e0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
127f0 64 73 32 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  ds2* */../*.** C
12800 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
12810 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e  e Connection Con
12820 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
12830 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  ns.**.** These c
12840 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
12850 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
12860 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
12870 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
12880 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
12890 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
128a0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
128b0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
128c0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
128d0 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
128e0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
128f0 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
12900 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
12910 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
12920 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
12930 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
12940 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
12950 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
12960 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
12970 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
12980 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62  from [sqlite3_db
12990 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
129a0 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
129b0 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
129c0 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f    ^The [sqlite3_
129d0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
129e0 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
129f0 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
12a00 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
12a10 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
12a20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
12a30 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12a40 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
12a50 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
12a60 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
12a70 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
12a80 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
12a90 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
12aa0 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  hree additional 
12ab0 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
12ac0 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a  etermine the .**
12ad0 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f   [lookaside memo
12ae0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f  ry allocator] co
12af0 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
12b00 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
12b10 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54  nnection]..** ^T
12b20 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
12b30 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72  t (the third par
12b40 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
12b50 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
12b60 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  is a.** pointer 
12b70 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66  to a memory buff
12b80 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f  er to use for lo
12b90 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a  okaside memory..
12ba0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
12bb0 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65  gument after the
12bc0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
12bd0 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a  _LOOKASIDE verb.
12be0 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69  ** may be NULL i
12bf0 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c  n which case SQL
12c00 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74  ite will allocat
12c10 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69  e the.** lookasi
12c20 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c 66  de buffer itself
12c30 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
12c40 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20  malloc()]. ^The 
12c50 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
12c60 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
12c70 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
12c80 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e   buffer slot.  ^
12c90 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
12ca0 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nt is the number
12cb0 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54   of.** slots.  T
12cc0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  he size of the b
12cd0 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72  uffer in the fir
12ce0 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
12cf0 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e   be greater than
12d00 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  .** or equal to 
12d10 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74  the product of t
12d20 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
12d30 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20  ird arguments.  
12d40 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75  The buffer.** mu
12d50 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  st be aligned to
12d60 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64   an 8-byte bound
12d70 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65  ary.  ^If the se
12d80 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
12d90 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  .** SQLITE_DBCON
12da0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73  FIG_LOOKASIDE is
12db0 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20   not a multiple 
12dc0 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65  of 8, it is inte
12dd0 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65  rnally.** rounde
12de0 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65  d down to the ne
12df0 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69  xt smaller multi
12e00 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65  ple of 8.  ^(The
12e10 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
12e20 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  y.** configurati
12e30 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61 73  on for a databas
12e40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e  e connection can
12e50 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64   only be changed
12e60 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f   when that.** co
12e70 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20  nnection is not 
12e80 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20  currently using 
12e90 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
12ea0 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f  , or in other wo
12eb0 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20  rds.** when the 
12ec0 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20  "current value" 
12ed0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
12ee0 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75  sqlite3_db_statu
12ef0 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e  s](D,[SQLITE_CON
12f00 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e  FIG_LOOKASIDE],.
12f10 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20  ..) is zero..** 
12f20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63  Any attempt to c
12f30 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
12f40 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69  ide memory confi
12f50 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f  guration when lo
12f60 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72  okaside.** memor
12f70 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76  y is in use leav
12f80 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  es the configura
12f90 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61  tion unchanged a
12fa0 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b  nd returns .** [
12fb0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c  SQLITE_BUSY].)^<
12fc0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
12fd0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
12fe0 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a  NABLE_FKEY</dt>.
12ff0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
13000 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
13010 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
13020 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e  e the enforcemen
13030 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e  t of.** [foreign
13040 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73   key constraints
13050 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64  ].  There should
13060 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
13070 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
13080 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
13090 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
130a0 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
130b0 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72  disable FK enfor
130c0 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74  cement,.** posit
130d0 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b  ive to enable FK
130e0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20   enforcement or 
130f0 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
13100 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
13110 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20  .** unchanged.  
13120 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
13130 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
13140 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
13150 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
13160 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
13170 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
13180 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  her FK enforceme
13190 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a  nt is off or on.
131a0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
131b0 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
131c0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
131d0 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
131e0 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
131f0 20 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66   case the FK enf
13200 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67  orcement setting
13210 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
13220 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
13230 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
13240 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52  CONFIG_ENABLE_TR
13250 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  IGGER</dt>.** <d
13260 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
13270 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
13280 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52  e or disable [CR
13290 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
132a0 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65  riggers]..** The
132b0 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
132c0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
132d0 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
132e0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
132f0 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
13300 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
13310 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f   triggers,.** po
13320 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
13330 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67   triggers or neg
13340 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74  ative to leave t
13350 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61  he setting uncha
13360 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nged..** The sec
13370 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
13380 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
13390 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
133a0 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
133b0 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
133c0 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72 69  cate whether tri
133d0 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62 6c  ggers are disabl
133e0 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a  ed or enabled.**
133f0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
13400 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
13410 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  d parameter may 
13420 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
13430 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63  r, in.** which c
13440 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ase the trigger 
13450 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
13460 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
13470 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a  dd>.**.** </dl>.
13480 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
13490 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
134a0 53 49 44 45 20 20 20 20 20 20 20 31 30 30 31 20  SIDE       1001 
134b0 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e   /* void* int in
134c0 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
134d0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
134e0 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30  BLE_FKEY     100
134f0 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  2  /* int int* *
13500 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
13510 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
13520 5f 54 52 49 47 47 45 52 20 20 31 30 30 33 20 20  _TRIGGER  1003  
13530 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a  /* int int* */..
13540 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
13550 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
13560 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
13570 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e  lt Codes.**.** ^
13580 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
13590 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
135a0 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  s() routine enab
135b0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
135c0 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  the.** [extended
135d0 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
135e0 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65  eature of SQLite
135f0 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20  . ^The extended 
13600 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
13610 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
13620 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
13630 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
13640 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lity..*/.int sql
13650 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
13660 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
13670 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
13680 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
13690 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
136a0 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20  wid.**.** ^Each 
136b0 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69  entry in an SQLi
136c0 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 75  te table has a u
136d0 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67  nique 64-bit sig
136e0 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b  ned.** integer k
136f0 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52  ey called the [R
13700 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e  OWID | "rowid"].
13710 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61   ^The rowid is a
13720 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a  lways available.
13730 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61  ** as an undecla
13740 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64  red column named
13750 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20   ROWID, OID, or 
13760 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20  _ROWID_ as long 
13770 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65  as those.** name
13780 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75  s are not also u
13790 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c  sed by explicitl
137a0 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
137b0 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74  ns. ^If.** the t
137c0 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d  able has a colum
137d0 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47  n of type [INTEG
137e0 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
137f0 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  then that column
13800 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61  .** is another a
13810 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77  lias for the row
13820 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  id..**.** ^This 
13830 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
13840 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
13850 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a  he most recent.*
13860 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
13870 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64  SERT] into the d
13880 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65  atabase from the
13890 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
138a0 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65  ction].** in the
138b0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
138c0 20 20 5e 41 73 20 6f 66 20 53 51 4c 69 74 65 20    ^As of SQLite 
138d0 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 74  version 3.7.7, t
138e0 68 69 73 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  his routines.** 
138f0 72 65 63 6f 72 64 73 20 74 68 65 20 6c 61 73 74  records the last
13900 20 69 6e 73 65 72 74 20 72 6f 77 69 64 20 6f 66   insert rowid of
13910 20 62 6f 74 68 20 6f 72 64 69 6e 61 72 79 20 74   both ordinary t
13920 61 62 6c 65 73 20 61 6e 64 20 5b 76 69 72 74 75  ables and [virtu
13930 61 6c 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20 5e  al tables]..** ^
13940 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c  If no successful
13950 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61   [INSERT]s.** ha
13960 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64  ve ever occurred
13970 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61 73   on that databas
13980 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65  e connection, ze
13990 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  ro is returned..
139a0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49  **.** ^(If an [I
139b0 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69  NSERT] occurs wi
139c0 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f  thin a trigger o
139d0 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74  r within a [virt
139e0 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65  ual table].** me
139f0 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20  thod, then this 
13a00 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74  routine will ret
13a10 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  urn the [rowid] 
13a20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a  of the inserted.
13a30 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61  ** row as long a
13a40 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  s the trigger or
13a50 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d   virtual table m
13a60 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67  ethod is running
13a70 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68  ..** But once th
13a80 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
13a90 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f  tual table metho
13aa0 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75  d ends, the valu
13ab0 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62  e returned .** b
13ac0 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  y this routine r
13ad0 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20 69  everts to what i
13ae0 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65  t was before the
13af0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
13b00 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74  ual.** table met
13b10 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a  hod began.)^.**.
13b20 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20  ** ^An [INSERT] 
13b30 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74  that fails due t
13b40 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  o a constraint v
13b50 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  iolation is not 
13b60 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  a.** successful 
13b70 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65  [INSERT] and doe
13b80 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
13b90 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
13ba0 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  by this.** routi
13bb0 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52  ne.  ^Thus INSER
13bc0 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52  T OR FAIL, INSER
13bd0 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53  T OR IGNORE, INS
13be0 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c  ERT OR ROLLBACK,
13bf0 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f  .** and INSERT O
13c00 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20  R ABORT make no 
13c10 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72  changes to the r
13c20 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
13c30 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77  his.** routine w
13c40 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74  hen their insert
13c50 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68  ion fails.  ^(Wh
13c60 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  en INSERT OR REP
13c70 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  LACE.** encounte
13c80 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  rs a constraint 
13c90 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f  violation, it do
13ca0 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68  es not fail.  Th
13cb0 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74  e.** INSERT cont
13cc0 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
13cd0 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69  ion after deleti
13ce0 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75  ng rows that cau
13cf0 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74  sed.** the const
13d00 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f  raint problem so
13d10 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
13d20 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63  CE will always c
13d30 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
13d40 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
13d50 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a  s interface.)^.*
13d60 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
13d70 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72  rposes of this r
13d80 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45  outine, an [INSE
13d90 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65  RT] is considere
13da0 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65  d to.** be succe
13db0 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74  ssful even if it
13dc0 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79   is subsequently
13dd0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
13de0 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
13df0 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20  n is accessible 
13e00 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  to SQL statement
13e10 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61  s via the.** [la
13e20 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
13e30 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
13e40 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
13e50 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66  rate thread perf
13e60 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45  orms a new [INSE
13e70 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  RT] on the same.
13e80 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
13e90 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65  ection while the
13ea0 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
13eb0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
13ec0 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  * function is ru
13ed0 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
13ee0 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
13ef0 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a  insert [rowid],.
13f00 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ** then the valu
13f10 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  e returned by [s
13f20 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
13f30 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a  rt_rowid()] is.*
13f40 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  * unpredictable 
13f50 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
13f60 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
13f70 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
13f80 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
13f90 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  wid]..*/.sqlite3
13fa0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c  _int64 sqlite3_l
13fb0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
13fc0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
13fd0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75  ** CAPI3REF: Cou
13fe0 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66  nt The Number Of
13ff0 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
14000 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
14010 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
14020 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61  number of databa
14030 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72  se rows that wer
14040 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20  e changed.** or 
14050 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
14060 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20  ted by the most 
14070 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
14080 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
14090 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61  .** on the [data
140a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
140b0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
140c0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
140d0 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61  r..** ^(Only cha
140e0 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69  nges that are di
140f0 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64  rectly specified
14100 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d   by the [INSERT]
14110 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f  , [UPDATE],.** o
14120 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
14130 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64  ment are counted
14140 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61  .  Auxiliary cha
14150 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a  nges caused by.*
14160 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66  * triggers or [f
14170 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
14180 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  ns] are not coun
14190 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a  ted.)^ Use the.*
141a0 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  * [sqlite3_total
141b0 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63  _changes()] func
141c0 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65  tion to find the
141d0 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
141e0 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c   changes.** incl
141f0 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61  uding changes ca
14200 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73  used by triggers
14210 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79   and foreign key
14220 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   actions..**.** 
14230 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69  ^Changes to a vi
14240 65 77 20 74 68 61 74 20 61 72 65 20 73 69 6d 75  ew that are simu
14250 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53  lated by an [INS
14260 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d  TEAD OF trigger]
14270 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  .** are not coun
14280 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20  ted.  Only real 
14290 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72  table changes ar
142a0 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a  e counted..**.**
142b0 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65   ^(A "row change
142c0 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f  " is a change to
142d0 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66   a single row of
142e0 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a   a single table.
142f0 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20  ** caused by an 
14300 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20  INSERT, DELETE, 
14310 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d  or UPDATE statem
14320 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a  ent.  Rows that.
14330 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61  ** are changed a
14340 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f  s side effects o
14350 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  f [REPLACE] cons
14360 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
14370 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20  n,.** rollback, 
14380 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
14390 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20  , [DROP TABLE], 
143a0 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a  or by any other.
143b0 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f  ** mechanisms do
143c0 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69   not count as di
143d0 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
143e0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69  .)^.**.** A "tri
143f0 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73  gger context" is
14400 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63   a scope of exec
14410 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e  ution that begin
14420 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69  s and.** ends wi
14430 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66  th the script of
14440 20 61 20 5b 43 52 45 41 54 45 20 54 52 49 47 47   a [CREATE TRIGG
14450 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a  ER | trigger]. .
14460 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74  ** Most SQL stat
14470 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76  ements are.** ev
14480 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20  aluated outside 
14490 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20  of any trigger. 
144a0 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f   This is the "to
144b0 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67  p level".** trig
144c0 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66  ger context.  If
144d0 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73   a trigger fires
144e0 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65   from the top le
144f0 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72  vel, a.** new tr
14500 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73  igger context is
14510 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65   entered for the
14520 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61   duration of tha
14530 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72  t one.** trigger
14540 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63  .  Subtriggers c
14550 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74  reate subcontext
14560 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61  s for their dura
14570 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  tion..**.** ^Cal
14580 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78  ling [sqlite3_ex
14590 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ec()] or [sqlite
145a0 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73  3_step()] recurs
145b0 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ively does.** no
145c0 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74  t create a new t
145d0 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
145e0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
145f0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
14600 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63   number of direc
14610 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e  t row changes in
14620 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63   the.** most rec
14630 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ent INSERT, UPDA
14640 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74  TE, or DELETE st
14650 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
14660 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67  he same.** trigg
14670 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  er context..**.*
14680 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61  * ^Thus, when ca
14690 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f  lled from the to
146a0 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75  p level, this fu
146b0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
146c0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
146d0 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
146e0 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
146f0 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
14700 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73  LETE.** that als
14710 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68  o occurred at th
14720 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28  e top level.  ^(
14730 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20  Within the body 
14740 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a  of a trigger,.**
14750 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
14760 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65  nges() interface
14770 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74   can be called t
14780 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
14790 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20  r of.** changes 
147a0 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
147b0 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49  ntly completed I
147c0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
147d0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74  r DELETE.** stat
147e0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
147f0 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d   body of the sam
14800 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f  e trigger..** Ho
14810 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65  wever, the numbe
14820 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20  r returned does 
14830 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e  not include chan
14840 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79  ges.** caused by
14850 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e   subtriggers sin
14860 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68  ce those have th
14870 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e  eir own context.
14880 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
14890 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  o the [sqlite3_t
148a0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
148b0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
148c0 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
148d0 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
148e0 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
148f0 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
14900 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
14910 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
14920 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
14930 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
14940 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
14950 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
14960 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
14970 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
14980 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65  rned.** is unpre
14990 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
149a0 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
149b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
149c0 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
149d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
149e0 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
149f0 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
14a00 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
14a10 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
14a20 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61  umber of row cha
14a30 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b  nges caused by [
14a40 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44  INSERT],.** [UPD
14a50 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ATE] or [DELETE]
14a60 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63   statements sinc
14a70 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  e the [database 
14a80 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20  connection] was 
14a90 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65  opened..** ^(The
14aa0 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20   count returned 
14ab0 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  by sqlite3_total
14ac0 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75  _changes() inclu
14ad0 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a  des all changes.
14ae0 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45  ** from all [CRE
14af0 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
14b00 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20  igger] contexts 
14b10 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65  and changes made
14b20 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20   by.** [foreign 
14b30 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f  key actions]. Ho
14b40 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f  wever,.** the co
14b50 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
14b60 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65  lude changes use
14b70 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b  d to implement [
14b80 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
14b90 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c  ints,.** do roll
14ba0 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70  backs or ABORT p
14bb0 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44  rocessing, or [D
14bc0 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65  ROP TABLE] proce
14bd0 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63  ssing.  The.** c
14be0 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ount does not in
14bf0 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69  clude rows of vi
14c00 65 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e  ews that fire an
14c10 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
14c20 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68  gger],.** though
14c30 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20   if the INSTEAD 
14c40 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73  OF trigger makes
14c50 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20   changes of its 
14c60 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67  own, those chang
14c70 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74  es .** are count
14c80 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71  ed.)^.** ^The sq
14c90 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
14ca0 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  ges() function c
14cb0 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65  ounts the change
14cc0 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20  s as soon as.** 
14cd0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68  the statement th
14ce0 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73  at makes them is
14cf0 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e   completed (when
14d00 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
14d10 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73  andle.** is pass
14d20 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ed to [sqlite3_r
14d30 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
14d40 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29  te3_finalize()])
14d50 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
14d60 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
14d70 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
14d80 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
14d90 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
14da0 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61  ], and the [tota
14db0 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  l_changes() SQL 
14dc0 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
14dd0 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
14de0 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
14df0 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
14e00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14e10 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
14e20 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
14e30 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
14e40 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
14e50 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20  .** returned is 
14e60 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
14e70 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
14e80 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
14e90 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73  _total_changes(s
14ea0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
14eb0 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72   CAPI3REF: Inter
14ec0 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e  rupt A Long-Runn
14ed0 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20  ing Query.**.** 
14ee0 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63  ^This function c
14ef0 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e  auses any pendin
14f00 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  g database opera
14f10 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e  tion to abort an
14f20 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69  d.** return at i
14f30 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f  ts earliest oppo
14f40 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f  rtunity. This ro
14f50 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c  utine is typical
14f60 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20  ly.** called in 
14f70 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73  response to a us
14f80 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61  er action such a
14f90 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63  s pressing "Canc
14fa0 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43  el".** or Ctrl-C
14fb0 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20   where the user 
14fc0 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65  wants a long que
14fd0 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  ry operation to 
14fe0 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74  halt.** immediat
14ff0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69  ely..**.** ^It i
15000 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  s safe to call t
15010 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d  his routine from
15020 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72   a thread differ
15030 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20  ent from the.** 
15040 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63  thread that is c
15050 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
15060 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70   the database op
15070 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74  eration.  But it
15080 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20  .** is not safe 
15090 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
150a0 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74  tine with a [dat
150b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
150c0 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f  ] that.** is clo
150d0 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f  sed or might clo
150e0 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65  se before sqlite
150f0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65  3_interrupt() re
15100 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  turns..**.** ^If
15110 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f   an SQL operatio
15120 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79  n is very nearly
15130 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65   finished at the
15140 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71   time when.** sq
15150 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
15160 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65  ) is called, the
15170 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68  n it might not h
15180 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69  ave an opportuni
15190 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65  ty.** to be inte
151a0 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68  rrupted and migh
151b0 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f  t continue to co
151c0 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  mpletion..**.** 
151d0 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ^An SQL operatio
151e0 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72  n that is interr
151f0 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72  upted will retur
15200 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  n [SQLITE_INTERR
15210 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  UPT]..** ^If the
15220 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c   interrupted SQL
15230 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e   operation is an
15240 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
15250 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68   or DELETE.** th
15260 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20  at is inside an 
15270 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
15280 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65  tion, then the e
15290 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f  ntire transactio
152a0 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c  n.** will be rol
152b0 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74  led back automat
152c0 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ically..**.** ^T
152d0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
152e0 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20  rupt(D) call is 
152f0 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20  in effect until 
15300 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75  all currently ru
15310 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
15320 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61  tements on [data
15330 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
15340 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41   D complete.  ^A
15350 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65  ny new SQL state
15360 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
15370 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
15380 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
15390 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64  rrupt() call and
153a0 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20   before the .** 
153b0 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
153c0 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  ts reaches zero 
153d0 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  are interrupted 
153e0 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62  as if they had b
153f0 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70  een.** running p
15400 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69  rior to the sqli
15410 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
15420 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20  call.  ^New SQL 
15430 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
15440 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
15450 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67  fter the running
15460 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74   statement count
15470 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
15480 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65  e.** not effecte
15490 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
154a0 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a  _interrupt()..**
154b0 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69   ^A call to sqli
154c0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
154d0 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65   that occurs whe
154e0 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72  n there are no r
154f0 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
15500 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f  atements is a no
15510 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65  -op and has no e
15520 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61  ffect on SQL sta
15530 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
15540 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
15550 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
15560 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72  terrupt() call r
15570 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66  eturns..**.** If
15580 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
15590 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20  nnection closes 
155a0 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69  while [sqlite3_i
155b0 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69  nterrupt()].** i
155c0 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62  s running then b
155d0 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c  ad things will l
155e0 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f  ikely happen..*/
155f0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e  .void sqlite3_in
15600 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a  terrupt(sqlite3*
15610 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
15620 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
15630 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
15640 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a  t Is Complete.**
15650 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
15660 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75  es are useful du
15670 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e  ring command-lin
15680 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72  e input to deter
15690 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63  mine if the.** c
156a0 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64  urrently entered
156b0 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66   text seems to f
156c0 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53  orm a complete S
156d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a  QL statement or.
156e0 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c  ** if additional
156f0 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64   input is needed
15700 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20   before sending 
15710 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a  the text into.**
15720 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73   SQLite for pars
15730 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ing.  ^These rou
15740 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69  tines return 1 i
15750 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  f the input stri
15760 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f  ng.** appears to
15770 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53   be a complete S
15780 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  QL statement.  ^
15790 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a  A statement is j
157a0 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63  udged to be.** c
157b0 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e  omplete if it en
157c0 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f  ds with a semico
157d0 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73  lon token and is
157e0 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66   not a prefix of
157f0 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65   a.** well-forme
15800 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52  d CREATE TRIGGER
15810 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65   statement.  ^Se
15820 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72  micolons that ar
15830 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69  e embedded withi
15840 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65  n.** string lite
15850 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69  rals or quoted i
15860 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20  dentifier names 
15870 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20  or comments are 
15880 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65  not.** independe
15890 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20  nt tokens (they 
158a0 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20  are part of the 
158b0 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74  token in which t
158c0 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64  hey are.** embed
158d0 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f  ded) and thus do
158e0 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20   not count as a 
158f0 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e  statement termin
15900 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61  ator.  ^Whitespa
15910 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e  ce.** and commen
15920 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74  ts that follow t
15930 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c  he final semicol
15940 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a  on are ignored..
15950 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
15960 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69  tines return 0 i
15970 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
15980 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20  is incomplete.  
15990 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ^If a.** memory 
159a0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73  allocation fails
159b0 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f  , then SQLITE_NO
159c0 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  MEM is returned.
159d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
159e0 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61  utines do not pa
159f0 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74  rse the SQL stat
15a00 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77  ements thus.** w
15a10 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73  ill not detect s
15a20 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63  yntactically inc
15a30 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a  orrect SQL..**.*
15a40 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61  * ^(If SQLite ha
15a50 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69  s not been initi
15a60 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71  alized using [sq
15a70 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
15a80 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f  ()] prior .** to
15a90 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65   invoking sqlite
15aa0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74  3_complete16() t
15ab0 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  hen sqlite3_init
15ac0 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
15ad0 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63  ked.** automatic
15ae0 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
15af0 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49  complete16().  I
15b00 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a  f that initializ
15b10 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20  ation fails,.** 
15b20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
15b30 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
15b40 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
15b50 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f  will be non-zero
15b60 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f  .** regardless o
15b70 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
15b80 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69   the input SQL i
15b90 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a  s complete.)^.**
15ba0 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
15bb0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
15bc0 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  te()] must be a 
15bd0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
15be0 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e  ** UTF-8 string.
15bf0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
15c00 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
15c10 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20  plete16()] must 
15c20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
15c30 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
15c40 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
15c50 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69  byte order..*/.i
15c60 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
15c70 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ete(const char *
15c80 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  sql);.int sqlite
15c90 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e  3_complete16(con
15ca0 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a  st void *sql);..
15cb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
15cc0 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62  Register A Callb
15cd0 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51  ack To Handle SQ
15ce0 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73  LITE_BUSY Errors
15cf0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
15d00 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c  tine sets a call
15d10 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68  back function th
15d20 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  at might be invo
15d30 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20  ked whenever.** 
15d40 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
15d50 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74  de to open a dat
15d60 61 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74  abase table that
15d70 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a   another thread.
15d80 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61  ** or process ha
15d90 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20  s locked..**.** 
15da0 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
15db0 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
15dc0 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
15dd0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
15de0 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69  RR_BLOCKED].** i
15df0 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
15e00 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f  iately upon enco
15e10 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63  untering the loc
15e20 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79  k.  ^If the busy
15e30 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
15e40 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  not NULL, then t
15e50 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68  he callback migh
15e60 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  t be invoked wit
15e70 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e  h two arguments.
15e80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
15e90 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
15ea0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  e busy handler i
15eb0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
15ec0 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68  void* pointer wh
15ed0 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68  ich.** is the th
15ee0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
15ef0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
15f00 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65  dler().  ^The se
15f10 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
15f20 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e  .** the busy han
15f30 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  dler callback is
15f40 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74   the number of t
15f50 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75  imes that the bu
15f60 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a  sy handler has.*
15f70 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66  * been invoked f
15f80 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20  or this locking 
15f90 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
15fa0 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  ** busy callback
15fb0 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e   returns 0, then
15fc0 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61   no additional a
15fd0 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65  ttempts are made
15fe0 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68   to.** access th
15ff0 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b  e database and [
16000 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
16010 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
16020 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e  OCKED] is return
16030 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63  ed..** ^If the c
16040 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
16050 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61  non-zero, then a
16060 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a  nother attempt.*
16070 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  * is made to ope
16080 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
16090 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74  or reading and t
160a0 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73  he cycle repeats
160b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73  ..**.** The pres
160c0 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68  ence of a busy h
160d0 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20  andler does not 
160e0 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69  guarantee that i
160f0 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  t will be invoke
16100 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20  d.** when there 
16110 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69  is lock contenti
16120 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64  on. ^If SQLite d
16130 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69  etermines that i
16140 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
16150 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c  .** handler coul
16160 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65  d result in a de
16170 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20  adlock, it will 
16180 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74  go ahead and ret
16190 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
161a0 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ].** or [SQLITE_
161b0 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69  IOERR_BLOCKED] i
161c0 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69  nstead of invoki
161d0 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ng the busy hand
161e0 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72  ler..** Consider
161f0 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72   a scenario wher
16200 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73  e one process is
16210 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20   holding a read 
16220 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20  lock that.** it 
16230 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f  is trying to pro
16240 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76  mote to a reserv
16250 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61  ed lock and.** a
16260 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
16270 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73  is holding a res
16280 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20  erved lock that 
16290 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20  it is trying.** 
162a0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e  to promote to an
162b0 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e   exclusive lock.
162c0 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63    The first proc
162d0 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65  ess cannot proce
162e0 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74  ed.** because it
162f0 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
16300 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
16310 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
16320 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65   cannot.** proce
16330 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ed because it is
16340 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
16350 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20  first.  If both 
16360 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76  processes.** inv
16370 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e  oke the busy han
16380 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77  dlers, neither w
16390 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f  ill make any pro
163a0 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72  gress.  Therefor
163b0 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74  e,.** SQLite ret
163c0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53  urns [SQLITE_BUS
163d0 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  Y] for the first
163e0 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67   process, hoping
163f0 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69   that this.** wi
16400 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69  ll induce the fi
16410 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72  rst process to r
16420 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20  elease its read 
16430 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a  lock and allow.*
16440 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  * the second pro
16450 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e  cess to proceed.
16460 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
16470 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63  ult busy callbac
16480 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  k is NULL..**.**
16490 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55   ^The [SQLITE_BU
164a0 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e  SY] error is con
164b0 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54  verted to [SQLIT
164c0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
164d0 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20  .** when SQLite 
164e0 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65  is in the middle
164f0 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e   of a large tran
16500 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c  saction where al
16510 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73  l the.** changes
16520 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e   will not fit in
16530 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  to the in-memory
16540 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20   cache.  SQLite 
16550 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20  will.** already 
16560 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20  hold a RESERVED 
16570 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61  lock on the data
16580 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69  base file, but i
16590 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72  t needs.** to pr
165a0 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20  omote this lock 
165b0 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20  to EXCLUSIVE so 
165c0 74 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c  that it can spil
165d0 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73  l cache.** pages
165e0 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61   into the databa
165f0 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20  se file without 
16600 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65  harm to concurre
16610 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20  nt.** readers.  
16620 5e 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65  ^If it is unable
16630 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20   to promote the 
16640 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69  lock, then the i
16650 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68  n-memory.** cach
16660 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69  e will be left i
16670 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e  n an inconsisten
16680 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74  t state and so t
16690 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65  he error.** code
166a0 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f   is promoted fro
166b0 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79  m the relatively
166c0 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f   benign [SQLITE_
166d0 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20  BUSY] to.** the 
166e0 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c  more severe [SQL
166f0 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
16700 44 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72  D].  ^This error
16710 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a   code promotion.
16720 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74  ** forces an aut
16730 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20  omatic rollback 
16740 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20  of the changes. 
16750 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68   See the.** <a h
16760 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69  ref="/cvstrac/wi
16770 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46  ki?p=CorruptionF
16780 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f  ollowingBusyErro
16790 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f  r">.** Corruptio
167a0 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
167b0 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67  ror</a> wiki pag
167c0 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69  e for a discussi
167d0 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69  on of why.** thi
167e0 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a  s is important..
167f0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
16800 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
16810 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
16820 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68  defined for each
16830 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
16840 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74  nnection].  Sett
16850 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68  ing a new busy h
16860 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e  andler clears an
16870 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  y.** previously 
16880 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20  set handler.)^  
16890 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69  ^Note that calli
168a0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
168b0 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77  _timeout()].** w
168c0 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20  ill also set or 
168d0 63 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68  clear the busy h
168e0 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  andler..**.** Th
168f0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
16900 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20  should not take 
16910 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63  any actions whic
16920 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20  h modify the.** 
16930 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16940 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
16950 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
16960 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74  r.  Any such act
16970 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69  ions.** result i
16980 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
16990 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62  vior..** .** A b
169a0 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74  usy handler must
169b0 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64   not close the d
169c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
169d0 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72  on.** or [prepar
169e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
169f0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
16a00 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a  usy handler..*/.
16a10 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
16a20 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
16a30 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  *, int(*)(void*,
16a40 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  int), void*);../
16a50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
16a60 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
16a70 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  t.**.** ^This ro
16a80 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71  utine sets a [sq
16a90 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
16aa0 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65  er | busy handle
16ab0 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a  r] that sleeps.*
16ac0 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65  * for a specifie
16ad0 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65  d amount of time
16ae0 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73   when a table is
16af0 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68   locked.  ^The h
16b00 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73  andler.** will s
16b10 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
16b20 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61  mes until at lea
16b30 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
16b40 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
16b50 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c  .** have accumul
16b60 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74  ated.  ^After at
16b70 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
16b80 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
16b90 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e  ping,.** the han
16ba0 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77  dler returns 0 w
16bb0 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c  hich causes [sql
16bc0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20  ite3_step()] to 
16bd0 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
16be0 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
16bf0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
16c00 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  ]..**.** ^Callin
16c10 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  g this routine w
16c20 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20  ith an argument 
16c30 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
16c40 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75  al to zero.** tu
16c50 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79  rns off all busy
16c60 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a   handlers..**.**
16c70 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
16c80 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
16c90 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  sy handler for a
16ca0 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
16cb0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16cc0 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76  ion] any any giv
16cd0 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61  en moment.  If a
16ce0 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64  nother busy hand
16cf0 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e  ler.** was defin
16d00 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69  ed  (using [sqli
16d10 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
16d20 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61  ()]) prior to ca
16d30 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f  lling.** this ro
16d40 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65  utine, that othe
16d50 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  r busy handler i
16d60 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a  s cleared.)^.*/.
16d70 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
16d80 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33  _timeout(sqlite3
16d90 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a  *, int ms);../*.
16da0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
16db0 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65  venience Routine
16dc0 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75  s For Running Qu
16dd0 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73  eries.**.** This
16de0 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74   is a legacy int
16df0 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70  erface that is p
16e00 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63  reserved for bac
16e10 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
16e20 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20  lity..** Use of 
16e30 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  this interface i
16e40 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65  s not recommende
16e50 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74  d..**.** Definit
16e60 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74  ion: A <b>result
16e70 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65   table</b> is me
16e80 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74  mory data struct
16e90 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74  ure created by t
16ea0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  he.** [sqlite3_g
16eb0 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65  et_table()] inte
16ec0 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74  rface.  A result
16ed0 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74   table records t
16ee0 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71  he.** complete q
16ef0 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f  uery results fro
16f00 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75  m one or more qu
16f10 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eries..**.** The
16f20 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61   table conceptua
16f30 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72  lly has a number
16f40 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c   of rows and col
16f50 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68  umns.  But.** th
16f60 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20  ese numbers are 
16f70 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20  not part of the 
16f80 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73  result table its
16f90 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e  elf.  These.** n
16fa0 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69  umbers are obtai
16fb0 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20  ned separately. 
16fc0 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75   Let N be the nu
16fd0 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20  mber of rows.** 
16fe0 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d  and M be the num
16ff0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a  ber of columns..
17000 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
17010 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79  able is an array
17020 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
17030 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
17040 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a  UTF-8 strings..*
17050 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31  * There are (N+1
17060 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20  )*M elements in 
17070 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20  the array.  The 
17080 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73  first M pointers
17090 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72   point.** to zer
170a0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
170b0 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61  ings that  conta
170c0 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  in the names of 
170d0 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20  the columns..** 
170e0 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e  The remaining en
170f0 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20  tries all point 
17100 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  to query results
17110 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72  .  NULL values r
17120 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c  esult.** in NULL
17130 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20   pointers.  All 
17140 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65  other values are
17150 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20   in their UTF-8 
17160 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
17170 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73  ** string repres
17180 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75  entation as retu
17190 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
171a0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e  _column_text()].
171b0 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
171c0 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73  table might cons
171d0 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ist of one or mo
171e0 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  re memory alloca
171f0 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20  tions..** It is 
17200 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73  not safe to pass
17210 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
17220 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c  directly to [sql
17230 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
17240 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
17250 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f  should be deallo
17260 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cated using [sql
17270 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
17280 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61  )]..**.** ^(As a
17290 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65  n example of the
172a0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f   result table fo
172b0 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20  rmat, suppose a 
172c0 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20  query result.** 
172d0 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
172e0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
172f0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
17300 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41   Name        | A
17310 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d  ge.**        ---
17320 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
17330 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41  ----.**        A
17340 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a  lice       | 43.
17350 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20  **        Bob   
17360 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20        | 28.**   
17370 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20       Cindy      
17380 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c   | 21.** </pre><
17390 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
173a0 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f  ** There are two
173b0 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61   column (M==2) a
173c0 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e  nd three rows (N
173d0 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a  ==3).  Thus the.
173e0 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  ** result table 
173f0 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20  has 8 entries.  
17400 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75  Suppose the resu
17410 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72  lt table is stor
17420 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61  ed.** in an arra
17430 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74  y names azResult
17440 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74  .  Then azResult
17450 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74   holds this cont
17460 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ent:.**.** <bloc
17470 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
17480 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
17490 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b  #91;0] = "Name";
174a0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
174b0 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67  ult&#91;1] = "Ag
174c0 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
174d0 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20  Result&#91;2] = 
174e0 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20  "Alice";.**     
174f0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
17500 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20  3] = "43";.**   
17510 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
17520 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a  1;4] = "Bob";.**
17530 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
17540 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a  &#91;5] = "28";.
17550 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
17560 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e  lt&#91;6] = "Cin
17570 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  dy";.**        a
17580 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d  zResult&#91;7] =
17590 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   "21";.** </pre>
175a0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
175b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
175c0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66  e3_get_table() f
175d0 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65  unction evaluate
175e0 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  s one or more.**
175f0 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72   semicolon-separ
17600 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
17610 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d  nts in the zero-
17620 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
17630 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74  .** string of it
17640 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  s 2nd parameter 
17650 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65  and returns a re
17660 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68  sult table to th
17670 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76  e.** pointer giv
17680 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61  en in its 3rd pa
17690 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  rameter..**.** A
176a0 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61  fter the applica
176b0 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65  tion has finishe
176c0 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c  d with the resul
176d0 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67  t from sqlite3_g
176e0 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69  et_table(),.** i
176f0 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20  t must pass the 
17700 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69  result table poi
17710 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
17720 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20  free_table() in 
17730 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65  order to.** rele
17740 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74  ase the memory t
17750 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64  hat was malloced
17760 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  .  Because of th
17770 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71  e way the.** [sq
17780 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
17790 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73  happens within s
177a0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
177b0 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a  (), the calling.
177c0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
177d0 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c   not try to call
177e0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
177f0 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c  ] directly.  Onl
17800 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  y.** [sqlite3_fr
17810 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61  ee_table()] is a
17820 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74  ble to release t
17830 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72  he memory proper
17840 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a  ly and safely..*
17850 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
17860 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74  _get_table() int
17870 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d  erface is implem
17880 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70  ented as a wrapp
17890 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
178a0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20  lite3_exec()].  
178b0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
178c0 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20  table() routine 
178d0 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63  does not have ac
178e0 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69  cess.** to any i
178f0 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72  nternal data str
17900 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74  uctures of SQLit
17910 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79  e.  It uses only
17920 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69   the public.** i
17930 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64  nterface defined
17940 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e   here.  As a con
17950 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73  sequence, errors
17960 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74   that occur in t
17970 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61  he.** wrapper la
17980 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74  yer outside of t
17990 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c  he internal [sql
179a0 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c  ite3_exec()] cal
179b0 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66  l are not.** ref
179c0 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71  lected in subseq
179d0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
179e0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
179f0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
17a00 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69  _errmsg()]..*/.i
17a10 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  nt sqlite3_get_t
17a20 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20  able(.  sqlite3 
17a30 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
17a40 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
17a50 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
17a60 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20  r *zSql,     /* 
17a70 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
17a80 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ted */.  char **
17a90 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f  *pazResult,    /
17aa0 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65  * Results of the
17ab0 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20   query */.  int 
17ac0 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20  *pnRow,         
17ad0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
17ae0 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74  esult rows writt
17af0 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74  en here */.  int
17b00 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20   *pnColumn,     
17b10 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
17b20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77  result columns w
17b30 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
17b40 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67   char **pzErrmsg
17b50 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
17b60 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
17b70 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69   */.);.void sqli
17b80 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63  te3_free_table(c
17b90 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a  har **result);..
17ba0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17bb0 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67  Formatted String
17bc0 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69   Printing Functi
17bd0 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
17be0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72  routines are wor
17bf0 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20  k-alikes of the 
17c00 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c  "printf()" famil
17c10 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  y of functions.*
17c20 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  * from the stand
17c30 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
17c40 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
17c50 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
17c60 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
17c70 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74  () routines writ
17c80 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c  e their.** resul
17c90 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  ts into memory o
17ca0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
17cb0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
17cc0 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20  .** The strings 
17cd0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
17ce0 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73  e two routines s
17cf0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65  hould be.** rele
17d00 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ased by [sqlite3
17d10 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68  _free()].  ^Both
17d20 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
17d30 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
17d40 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d  er if [sqlite3_m
17d50 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62  alloc()] is unab
17d60 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65  le to allocate e
17d70 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20  nough.** memory 
17d80 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
17d90 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a  lting string..**
17da0 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
17db0 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  3_snprintf() rou
17dc0 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
17dd0 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20  to "snprintf()" 
17de0 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
17df0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20  dard C library. 
17e00 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77   The result is w
17e10 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a  ritten into the.
17e20 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69  ** buffer suppli
17e30 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
17e40 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65   parameter whose
17e50 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62   size is given b
17e60 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  y.** the first p
17e70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74  arameter. Note t
17e80 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66  hat the order of
17e90 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77   the.** first tw
17ea0 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  o parameters is 
17eb0 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e  reversed from sn
17ec0 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69  printf().)^  Thi
17ed0 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f  s is an.** histo
17ee0 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74  rical accident t
17ef0 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69  hat cannot be fi
17f00 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  xed without brea
17f10 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64  king.** backward
17f20 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
17f30 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68    ^(Note also th
17f40 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
17f50 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
17f60 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
17f70 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
17f80 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
17f90 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
17fa0 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
17fb0 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
17fc0 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68  .)^  We admit th
17fd0 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  at.** the number
17fe0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77   of characters w
17ff0 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20  ritten would be 
18000 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65  a more useful re
18010 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75  turn.** value bu
18020 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e  t we cannot chan
18030 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ge the implement
18040 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
18050 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e  _snprintf().** n
18060 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ow without break
18070 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ing compatibilit
18080 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e  y..**.** ^As lon
18090 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
180a0 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
180b0 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
180c0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
180d0 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
180e0 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
180f0 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
18100 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72  nated.  ^The fir
18110 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
18120 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c  "n" is the total
18130 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
18140 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73  fer, including s
18150 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  pace for.** the 
18160 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
18170 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74    So the longest
18180 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e   string that can
18190 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a   be completely.*
181a0 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62  * written will b
181b0 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73  e n-1 characters
181c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
181d0 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29  ite3_vsnprintf()
181e0 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61   routine is a va
181f0 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66  rargs version of
18200 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
18210 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  f()..**.** These
18220 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d   routines all im
18230 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64  plement some add
18240 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69  itional formatti
18250 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68  ng.** options th
18260 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  at are useful fo
18270 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53  r constructing S
18280 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
18290 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75  * All of the usu
182a0 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d  al printf() form
182b0 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61  atting options a
182c0 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69  pply.  In additi
182d0 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20  on, there.** is 
182e0 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20  are "%q", "%Q", 
182f0 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73  and "%z" options
18300 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71  ..**.** ^(The %q
18310 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
18320 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74  ke %s in that it
18330 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e   substitutes a n
18340 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ul-terminated.**
18350 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65   string from the
18360 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20   argument list. 
18370 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75   But %q also dou
18380 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20  bles every '\'' 
18390 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71  character..** %q
183a0 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72   is designed for
183b0 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74   use inside a st
183c0 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20  ring literal.)^ 
183d0 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63   By doubling eac
183e0 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63  h '\''.** charac
183f0 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74  ter it escapes t
18400 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e  hat character an
18410 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62  d allows it to b
18420 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a  e inserted into.
18430 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a  ** the string..*
18440 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65  *.** For example
18450 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72  , assume the str
18460 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65  ing variable zTe
18470 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74  xt contains text
18480 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
18490 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
184a0 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
184b0 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68  Text = "It's a h
184c0 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c  appy day!";.** <
184d0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
184e0 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e  e>.**.** One can
184f0 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69   use this text i
18500 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
18510 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  nt as follows:.*
18520 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
18530 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
18540 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
18550 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
18560 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
18570 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29  S('%q')", zText)
18580 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
18590 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
185a0 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
185b0 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
185c0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
185d0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61  uote>.**.** Beca
185e0 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61  use the %q forma
185f0 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64  t string is used
18600 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61  , the '\'' chara
18610 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a  cter in zText.**
18620 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20   is escaped and 
18630 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65  the SQL generate
18640 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  d is as follows:
18650 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
18660 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
18670 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
18680 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20  VALUES('It''s a 
18690 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20  happy day!').** 
186a0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
186b0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te>.**.** This i
186c0 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20  s correct.  Had 
186d0 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65  we used %s inste
186e0 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65  ad of %q, the ge
186f0 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77  nerated SQL.** w
18700 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64  ould have looked
18710 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
18720 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
18730 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
18740 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
18750 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20  S('It's a happy 
18760 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65  day!');.** </pre
18770 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
18780 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64  *.** This second
18790 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53   example is an S
187a0 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e  QL syntax error.
187b0 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72    As a general r
187c0 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a  ule you should.*
187d0 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20  * always use %q 
187e0 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68  instead of %s wh
187f0 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78  en inserting tex
18800 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20  t into a string 
18810 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  literal..**.** ^
18820 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77  (The %Q option w
18830 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63  orks like %q exc
18840 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73  ept it also adds
18850 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61   single quotes a
18860 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74  round.** the out
18870 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61  side of the tota
18880 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74  l string.  Addit
18890 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20  ionally, if the 
188a0 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
188b0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  .** argument lis
188c0 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
188d0 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75  ter, %Q substitu
188e0 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55  tes the text "NU
188f0 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20  LL" (without.** 
18900 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29  single quotes).)
18910 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70  ^  So, for examp
18920 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61  le, one could sa
18930 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  y:.**.** <blockq
18940 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
18950 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
18960 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
18970 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
18980 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78  ALUES(%Q)", zTex
18990 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
189a0 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
189b0 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
189c0 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
189d0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
189e0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
189f0 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c  e code above wil
18a00 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65  l render a corre
18a10 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ct SQL statement
18a20 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20   in the zSQL.** 
18a30 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66  variable even if
18a40 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61   the zText varia
18a50 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ble is a NULL po
18a60 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  inter..**.** ^(T
18a70 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
18a80 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
18a90 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69  like "%s" but wi
18aa0 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
18ab0 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
18ac0 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
18ad0 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
18ae0 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
18af0 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
18b00 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
18b10 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
18b20 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20  ring.)^.*/.char 
18b30 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  *sqlite3_mprintf
18b40 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
18b50 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
18b60 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  _vmprintf(const 
18b70 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
18b80 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73  .char *sqlite3_s
18b90 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
18ba0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
18bb0 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
18bc0 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74  e3_vsnprintf(int
18bd0 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
18be0 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f  r*, va_list);../
18bf0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
18c00 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
18c10 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a   Subsystem.**.**
18c20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
18c30 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65   uses these thre
18c40 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61  e routines for a
18c50 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a  ll of its own.**
18c60 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79   internal memory
18c70 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
18c80 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65  s. "Core" in the
18c90 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
18ca0 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69  ce.** does not i
18cb0 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67  nclude operating
18cc0 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
18cd0 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
18ce0 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e  ion.  The.** Win
18cf0 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61  dows VFS uses na
18d00 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  tive malloc() an
18d10 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d  d free() for som
18d20 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  e operations..**
18d30 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
18d40 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
18d50 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
18d60 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
18d70 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
18d80 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
18d90 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
18da0 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
18db0 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
18dc0 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61  _malloc() is una
18dd0 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75  ble to obtain su
18de0 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a  fficient free.**
18df0 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75   memory, it retu
18e00 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
18e10 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72  er.  ^If the par
18e20 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73  ameter N to.** s
18e30 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
18e40 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74  is zero or negat
18e50 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ive then sqlite3
18e60 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  _malloc() return
18e70 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
18e80 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ter..**.** ^Call
18e90 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
18ea0 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  () with a pointe
18eb0 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  r previously ret
18ec0 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
18ed0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
18ee0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
18ef0 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20  ) releases that 
18f00 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61  memory so.** tha
18f10 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65  t it might be re
18f20 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  used.  ^The sqli
18f30 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69  te3_free() routi
18f40 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70  ne is.** a no-op
18f50 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69   if is called wi
18f60 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
18f70 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55  r.  Passing a NU
18f80 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f  LL pointer.** to
18f90 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
18fa0 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66  is harmless.  Af
18fb0 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c  ter being freed,
18fc0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c   memory.** shoul
18fd0 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61  d neither be rea
18fe0 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20  d nor written.  
18ff0 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65  Even reading pre
19000 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a  viously freed.**
19010 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65   memory might re
19020 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e  sult in a segmen
19030 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20  tation fault or 
19040 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
19050 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f  or..** Memory co
19060 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d  rruption, a segm
19070 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20  entation fault, 
19080 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
19090 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72  error.** might r
190a0 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33  esult if sqlite3
190b0 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65  _free() is calle
190c0 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  d with a non-NUL
190d0 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a  L pointer that.*
190e0 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e  * was not obtain
190f0 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
19100 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
19110 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
19120 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
19130 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74  e3_realloc() int
19140 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
19150 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70  to resize a.** p
19160 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rior memory allo
19170 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20  cation to be at 
19180 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77  least N bytes, w
19190 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a  here N is the.**
191a0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
191b0 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61  r.  The memory a
191c0 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20  llocation to be 
191d0 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66  resized is the f
191e0 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
191f0 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69  r.)^ ^ If the fi
19200 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
19210 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
19220 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  ().** is a NULL 
19230 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73  pointer then its
19240 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65   behavior is ide
19250 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e  ntical to callin
19260 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  g.** sqlite3_mal
19270 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69  loc(N) where N i
19280 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
19290 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
192a0 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20  3_realloc()..** 
192b0 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70  ^If the second p
192c0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
192d0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73  te3_realloc() is
192e0 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61   zero or.** nega
192f0 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65  tive then the be
19300 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c  havior is exactl
19310 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61  y the same as ca
19320 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
19330 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50  _free(P) where P
19340 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
19350 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
19360 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
19370 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   ^sqlite3_reallo
19380 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  c() returns a po
19390 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
193a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
193b0 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  of at least N by
193c0 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e  tes in size or N
193d0 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e  ULL if sufficien
193e0 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76  t memory is unav
193f0 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20  ailable..** ^If 
19400 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  M is the size of
19410 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
19420 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28  ation, then min(
19430 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66  N,M) bytes.** of
19440 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
19450 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64  ation are copied
19460 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e   into the beginn
19470 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65  ing of buffer re
19480 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
19490 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61  ite3_realloc() a
194a0 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  nd the prior all
194b0 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64  ocation is freed
194c0 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
194d0 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
194e0 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ns NULL, then th
194f0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
19500 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65  on.** is not fre
19510 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ed..**.** ^The m
19520 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62  emory returned b
19530 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
19540 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
19550 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61  ealloc().** is a
19560 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f  lways aligned to
19570 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62   at least an 8 b
19580 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72  yte boundary, or
19590 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20   to a.** 4 byte 
195a0 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20  boundary if the 
195b0 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41  [SQLITE_4_BYTE_A
195c0 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63  LIGNED_MALLOC] c
195d0 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
195e0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ption is used..*
195f0 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76  *.** In SQLite v
19600 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64  ersion 3.5.0 and
19610 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70   3.5.1, it was p
19620 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e  ossible to defin
19630 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f  e.** the SQLITE_
19640 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f  OMIT_MEMORY_ALLO
19650 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75  CATION which wou
19660 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69  ld cause the bui
19670 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lt-in.** impleme
19680 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65  ntation of these
19690 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
196a0 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63  omitted.  That c
196b0 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
196c0 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64  no longer provid
196d0 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d  ed.  Only built-
196e0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
196f0 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  tors can be used
19700 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64  ..**.** The Wind
19710 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ows OS interface
19720 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   layer calls.** 
19730 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
19740 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64  c() and free() d
19750 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e  irectly when con
19760 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e  verting.** filen
19770 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65  ames between the
19780 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
19790 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  used by SQLite.*
197a0 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66  * and whatever f
197b0 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67  ilename encoding
197c0 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
197d0 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f  particular Windo
197e0 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69  ws.** installati
197f0 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f  on.  Memory allo
19800 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72  cation errors ar
19810 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a  e detected, but.
19820 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65 70 6f  ** they are repo
19830 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
19840 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
19850 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
19860 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
19870 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
19880 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
19890 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b  r arguments to [
198a0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
198b0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
198c0 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20  lloc()].** must 
198d0 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f  be either NULL o
198e0 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20  r else pointers 
198f0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
19900 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74  prior.** invocat
19910 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
19920 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
19930 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
19940 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f   that have.** no
19950 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61  t yet been relea
19960 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  sed..**.** The a
19970 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
19980 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74  not read or writ
19990 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a  e any part of.**
199a0 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f   a block of memo
199b0 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20  ry after it has 
199c0 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73  been released us
199d0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
199e0 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  free()] or [sqli
199f0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a  te3_realloc()]..
19a00 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
19a10 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f  _malloc(int);.vo
19a20 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
19a30 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  loc(void*, int);
19a40 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
19a50 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ee(void*);../*.*
19a60 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
19a70 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61  ry Allocator Sta
19a80 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51  tistics.**.** SQ
19a90 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68  Lite provides th
19aa0 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63  ese two interfac
19ab0 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67  es for reporting
19ac0 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a   on the status.*
19ad0 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
19ae0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71  3_malloc()], [sq
19af0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61  lite3_free()], a
19b00 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
19b10 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e  loc()].** routin
19b20 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74  es, which form t
19b30 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  he built-in memo
19b40 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
19b50 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  bsystem..**.** ^
19b60 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
19b70 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74  ory_used()] rout
19b80 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
19b90 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a  number of bytes.
19ba0 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72  ** of memory cur
19bb0 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69  rently outstandi
19bc0 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74  ng (malloced but
19bd0 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20   not freed)..** 
19be0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
19bf0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
19c00 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
19c10 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
19c20 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74   value of [sqlit
19c30 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
19c40 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68  ] since the high
19c50 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77  -water mark.** w
19c60 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20  as last reset.  
19c70 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
19c80 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
19c90 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
19ca0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
19cb0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
19cc0 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20  ()] include any 
19cd0 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65  overhead.** adde
19ce0 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69  d by SQLite in i
19cf0 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ts implementatio
19d00 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
19d10 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20  lloc()],.** but 
19d20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64  not overhead add
19d30 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e  ed by the any un
19d40 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20  derlying system 
19d50 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69  library.** routi
19d60 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65  nes that [sqlite
19d70 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20  3_malloc()] may 
19d80 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  call..**.** ^The
19d90 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74   memory high-wat
19da0 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74  er mark is reset
19db0 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   to the current 
19dc0 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c  value of.** [sql
19dd0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
19de0 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ()] if and only 
19df0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
19e00 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
19e10 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
19e20 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54  ()] is true.  ^T
19e30 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
19e40 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
19e50 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
19e60 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67  r(1)] is the hig
19e70 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
19e80 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73  prior to the res
19e90 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  et..*/.sqlite3_i
19ea0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
19eb0 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a  ory_used(void);.
19ec0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
19ed0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
19ee0 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74  hwater(int reset
19ef0 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Flag);../*.** CA
19f00 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52  PI3REF: Pseudo-R
19f10 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e  andom Number Gen
19f20 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c  erator.**.** SQL
19f30 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68  ite contains a h
19f40 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75  igh-quality pseu
19f50 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72  do-random number
19f60 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47   generator (PRNG
19f70 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c  ) used to.** sel
19f80 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49  ect random [ROWI
19f90 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e  D | ROWIDs] when
19fa0 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72   inserting new r
19fb0 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61  ecords into a ta
19fc0 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65  ble that.** alre
19fd0 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72  ady uses the lar
19fe0 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52  gest possible [R
19ff0 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47  OWID].  The PRNG
1a000 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f   is also used fo
1a010 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69  r.** the build-i
1a020 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72  n random() and r
1a030 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20  andomblob() SQL 
1a040 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73  functions.  This
1a050 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
1a060 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  s.** application
1a070 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
1a080 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74  same PRNG for ot
1a090 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a  her purposes..**
1a0a0 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74  .** ^A call to t
1a0b0 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
1a0c0 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61  es N bytes of ra
1a0d0 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75  ndomness into bu
1a0e0 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ffer P..**.** ^T
1a0f0 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
1a100 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e  is routine is in
1a110 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e  voked (either in
1a120 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a  ternally or by.*
1a130 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
1a140 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73  n) the PRNG is s
1a150 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64  eeded using rand
1a160 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a  omness obtained.
1a170 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e  ** from the xRan
1a180 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f  domness method o
1a190 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
1a1a0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
1a1b0 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73  ct..** ^On all s
1a1c0 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
1a1d0 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64  tions, the pseud
1a1e0 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20  o-randomness is 
1a1f0 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74  generated.** int
1a200 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68  ernally and with
1a210 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20  out recourse to 
1a220 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
1a230 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a  ] xRandomness.**
1a240 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64   method..*/.void
1a250 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e   sqlite3_randomn
1a260 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20  ess(int N, void 
1a270 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *P);../*.** CAPI
1a280 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69  3REF: Compile-Ti
1a290 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  me Authorization
1a2a0 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
1a2b0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
1a2c0 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68  egisters an auth
1a2d0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1a2e0 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
1a2f0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
1a300 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70  onnection], supp
1a310 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
1a320 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  t argument..** ^
1a330 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
1a340 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1a350 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
1a360 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
1a370 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
1a380 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1a390 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
1a3a0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
1a3b0 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
1a3c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1a3d0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1a3e0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
1a3f0 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a    ^At various.**
1a400 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74   points during t
1a410 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70  he compilation p
1a420 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63  rocess, as logic
1a430 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65   is being create
1a440 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20  d.** to perform 
1a450 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c  various actions,
1a460 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1a470 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1a480 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66  ked to.** see if
1a490 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61   those actions a
1a4a0 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68  re allowed.  ^Th
1a4b0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1a4c0 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20  lback should.** 
1a4d0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
1a4e0 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20  K] to allow the 
1a4f0 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f  action, [SQLITE_
1a500 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c  IGNORE] to disal
1a510 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69  low the.** speci
1a520 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61  fic action but a
1a530 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61  llow the SQL sta
1a540 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e  tement to contin
1a550 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ue to be.** comp
1a560 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  iled, or [SQLITE
1a570 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20  _DENY] to cause 
1a580 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73  the entire SQL s
1a590 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a  tatement to be.*
1a5a0 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20  * rejected with 
1a5b0 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74  an error.  ^If t
1a5c0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1a5d0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
1a5e0 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65  * any value othe
1a5f0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49  r than [SQLITE_I
1a600 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  GNORE], [SQLITE_
1a610 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OK], or [SQLITE_
1a620 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  DENY].** then th
1a630 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
1a640 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
1a650 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
1a660 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68   triggered.** th
1a670 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  e authorizer wil
1a680 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
1a690 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
1a6a0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c  .** When the cal
1a6b0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
1a6c0 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20  QLITE_OK], that 
1a6d0 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74  means the operat
1a6e0 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  ion.** requested
1a6f0 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74   is ok.  ^When t
1a700 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1a710 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59  rns [SQLITE_DENY
1a720 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ], the.** [sqlit
1a730 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1a740 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
1a750 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
1a760 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  ed the.** author
1a770 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
1a780 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
1a790 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20  sage explaining 
1a7a0 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69  that.** access i
1a7b0 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a  s denied. .**.**
1a7c0 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
1a7d0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
1a7e0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1a7f0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
1a800 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
1a810 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
1a820 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1a830 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20  er() interface. 
1a840 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
1a850 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
1a860 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
1a870 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43  nteger [SQLITE_C
1a880 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
1a890 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
1a8a0 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75  s.** the particu
1a8b0 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  lar action to be
1a8c0 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68   authorized. ^Th
1a8d0 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
1a8e0 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
1a8f0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
1a900 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  ack are zero-ter
1a910 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
1a920 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64  that contain add
1a930 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69  itional.** detai
1a940 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
1a950 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
1a960 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ized..**.** ^If 
1a970 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
1a980 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  is [SQLITE_READ]
1a990 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  .** and the call
1a9a0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1a9b0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
1a9c0 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
1a9d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74  ed statement] st
1a9e0 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
1a9f0 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69  ructed to substi
1aa00 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76  tute.** a NULL v
1aa10 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
1aa20 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
1aa30 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
1aa40 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69  e.** been read i
1aa50 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61  f [SQLITE_OK] ha
1aa60 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e  d been returned.
1aa70 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47    The [SQLITE_IG
1aa80 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20  NORE].** return 
1aa90 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64  can be used to d
1aaa0 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64  eny an untrusted
1aab0 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20   user access to 
1aac0 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f  individual.** co
1aad0 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65  lumns of a table
1aae0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  ..** ^If the act
1aaf0 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
1ab00 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20  ITE_DELETE] and 
1ab10 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1ab20 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
1ab30 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
1ab40 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74   [DELETE] operat
1ab50 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74  ion proceeds but
1ab60 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74   the.** [truncat
1ab70 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20  e optimization] 
1ab80 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20  is disabled and 
1ab90 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c  all rows are del
1aba0 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  eted individuall
1abb0 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  y..**.** An auth
1abc0 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
1abd0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
1abe0 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67  pare | preparing
1abf0 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  ].** SQL stateme
1ac00 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72  nts from an untr
1ac10 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f  usted source, to
1ac20 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
1ac30 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
1ac40 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ** do not try to
1ac50 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65   access data the
1ac60 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  y are not allowe
1ac70 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61  d to see, or tha
1ac80 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
1ac90 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20   try to execute 
1aca0 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d  malicious statem
1acb0 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65  ents that damage
1acc0 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20   the database.  
1acd0 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
1ace0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
1acf0 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20  ay allow a user 
1ad00 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61  to enter arbitra
1ad10 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65  ry.** SQL querie
1ad20 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e  s for evaluation
1ad30 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20   by a database. 
1ad40 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61   But the applica
1ad50 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  tion does.** not
1ad60 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74   want the user t
1ad70 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b  o be able to mak
1ad80 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e  e arbitrary chan
1ad90 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ges to the.** da
1ada0 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68  tabase.  An auth
1adb0 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65  orizer could the
1adc0 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63  n be put in plac
1add0 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75  e while the.** u
1ade0 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20  ser-entered SQL 
1adf0 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65  is being [sqlite
1ae00 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
1ae10 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69  ared] that.** di
1ae20 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
1ae30 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43  ng except [SELEC
1ae40 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
1ae50 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
1ae60 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70  s that need to p
1ae70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20  rocess SQL from 
1ae80 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
1ae90 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20  s.** might also 
1aea0 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e  consider lowerin
1aeb0 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74  g resource limit
1aec0 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  s using [sqlite3
1aed0 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64  _limit()].** and
1aee0 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61   limiting databa
1aef0 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68  se size using th
1af00 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  e [max_page_coun
1af10 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69  t] [PRAGMA].** i
1af20 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73  n addition to us
1af30 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ing an authorize
1af40 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  r..**.** ^(Only 
1af50 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69  a single authori
1af60 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c  zer can be in pl
1af70 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73  ace on a databas
1af80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1af90 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68  at a time.  Each
1afa0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
1afb0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1afc0 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
1afd0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29   previous call.)
1afe0 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20  ^  ^Disable the 
1aff0 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e  authorizer by in
1b000 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20  stalling a NULL 
1b010 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  callback..** The
1b020 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64   authorizer is d
1b030 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
1b040 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  lt..**.** The au
1b050 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1b060 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
1b070 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
1b080 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
1b090 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b0a0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1b0b0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1b0c0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65  allback..** Note
1b0d0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
1b0e0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
1b0f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1b100 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
1b110 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
1b120 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
1b130 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
1b140 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
1b150 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
1b160 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f   ^When [sqlite3_
1b170 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73  prepare_v2()] is
1b180 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65   used to prepare
1b190 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68   a statement, th
1b1a0 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d  e.** statement m
1b1b0 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61  ight be re-prepa
1b1c0 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69  red during [sqli
1b1d0 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20  te3_step()] due 
1b1e0 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20  to a .** schema 
1b1f0 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20  change.  Hence, 
1b200 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1b210 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68  should ensure th
1b220 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63  at the.** correc
1b230 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  t authorizer cal
1b240 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e  lback remains in
1b250 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68   place during th
1b260 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
1b270 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  )]..**.** ^Note 
1b280 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
1b290 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1b2a0 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72  invoked only dur
1b2b0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1b2c0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
1b2d0 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
1b2e0 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
1b2f0 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
1b300 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
1b310 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
1b320 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
1b330 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61  unless.** as sta
1b340 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69  ted in the previ
1b350 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73  ous paragraph, s
1b360 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
1b370 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33  vokes.** sqlite3
1b380 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f  _prepare_v2() to
1b390 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61   reprepare a sta
1b3a0 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73  tement after a s
1b3b0 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f  chema change..*/
1b3c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74  .int sqlite3_set
1b3d0 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73  _authorizer(.  s
1b3e0 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28  qlite3*,.  int (
1b3f0 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e  *xAuth)(void*,in
1b400 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  t,const char*,co
1b410 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1b420 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1b430 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65  *),.  void *pUse
1b440 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  rData.);../*.** 
1b450 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
1b460 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65  izer Return Code
1b470 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
1b480 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1b490 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
1b4a0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1b4b0 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75  on] must.** retu
1b4c0 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  rn either [SQLIT
1b4d0 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  E_OK] or one of 
1b4e0 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61  these two consta
1b4f0 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20  nts in order.** 
1b500 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65  to signal SQLite
1b510 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1b520 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65  the action is pe
1b530 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68  rmitted.  See th
1b540 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65  e.** [sqlite3_se
1b550 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
1b560 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65  uthorizer docume
1b570 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64  ntation] for add
1b580 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
1b590 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  mation..**.** No
1b5a0 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49  te that SQLITE_I
1b5b0 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73  GNORE is also us
1b5c0 65 64 20 61 73 20 61 20 5b 53 51 4c 49 54 45 5f  ed as a [SQLITE_
1b5d0 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75 72  ROLLBACK | retur
1b5e0 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20  n code].** from 
1b5f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61  the [sqlite3_vta
1b600 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d  b_on_conflict()]
1b610 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23   interface..*/.#
1b620 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
1b630 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72  NY   1   /* Abor
1b640 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
1b650 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ent with an erro
1b660 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
1b670 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f  ITE_IGNORE 2   /
1b680 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63  * Don't allow ac
1b690 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20  cess, but don't 
1b6a0 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f  generate an erro
1b6b0 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  r */../*.** CAPI
1b6c0 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
1b6d0 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a   Action Codes.**
1b6e0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
1b6f0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1b700 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
1b710 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
1b720 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68  k function.** th
1b730 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  at is invoked to
1b740 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61   authorize certa
1b750 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  in SQL statement
1b760 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a   actions.  The.*
1b770 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
1b780 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
1b790 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
1b7a0 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69   code that speci
1b7b0 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74  fies.** what act
1b7c0 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74  ion is being aut
1b7d0 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20  horized.  These 
1b7e0 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20  are the integer 
1b7f0 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61  action codes tha
1b800 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  t.** the authori
1b810 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79  zer callback may
1b820 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a   be passed..**.*
1b830 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63  * These action c
1b840 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69  ode values signi
1b850 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  fy what kind of 
1b860 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20  operation is to 
1b870 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64  be.** authorized
1b880 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34  .  The 3rd and 4
1b890 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
1b8a0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69   the authorizati
1b8b0 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  on.** callback f
1b8c0 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20  unction will be 
1b8d0 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55  parameters or NU
1b8e0 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  LL depending on 
1b8f0 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a  which of these.*
1b900 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20  * codes is used 
1b910 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
1b920 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20  rameter.  ^(The 
1b930 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
1b940 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
1b950 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
1b960 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
1b970 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c  atabase ("main",
1b980 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e   "temp",.** etc.
1b990 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e  ) if applicable.
1b9a0 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72  )^  ^The 6th par
1b9b0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
1b9c0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1b9d0 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  k.** is the name
1b9e0 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
1b9f0 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
1ba00 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
1ba10 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68  nsible for.** th
1ba20 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
1ba30 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
1ba40 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
1ba50 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
1ba60 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51  .** top-level SQ
1ba70 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a  L code..*/./****
1ba80 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ba90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1baa0 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a  ******* 3rd ****
1bab0 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a  ******** 4th ***
1bac0 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e  ********/.#defin
1bad0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1bae0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31  INDEX          1
1baf0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1bb00 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
1bb10 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1bb20 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1bb30 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20  ABLE          2 
1bb40 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1bb50 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1bb60 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1bb70 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1bb80 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20  MP_INDEX     3  
1bb90 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1bba0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1bbb0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1bbc0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1bbd0 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20  P_TABLE     4   
1bbe0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1bbf0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1bc00 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1bc10 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1bc20 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f  _TRIGGER   5   /
1bc30 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
1bc40 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1bc50 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1bc60 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1bc70 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a  VIEW      6   /*
1bc80 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
1bc90 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1bca0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1bcb0 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45  TE_CREATE_TRIGGE
1bcc0 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  R        7   /* 
1bcd0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1bce0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1bcf0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1bd00 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20  E_CREATE_VIEW   
1bd10 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56          8   /* V
1bd20 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1bd30 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1bd40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1bd50 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
1bd60 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61         9   /* Ta
1bd70 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1bd80 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1bd90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1bda0 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20  DROP_INDEX      
1bdb0 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64       10   /* Ind
1bdc0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1bdd0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1bde0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1bdf0 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ROP_TABLE       
1be00 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c      11   /* Tabl
1be10 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1be20 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1be30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1be40 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  OP_TEMP_INDEX   
1be50 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78     12   /* Index
1be60 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1be70 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1be80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1be90 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  P_TEMP_TABLE    
1bea0 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    13   /* Table 
1beb0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1bec0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1bed0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1bee0 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
1bef0 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72   14   /* Trigger
1bf00 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1bf10 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1bf20 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1bf30 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20  TEMP_VIEW       
1bf40 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  15   /* View Nam
1bf50 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1bf60 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1bf70 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1bf80 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31  RIGGER         1
1bf90 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  6   /* Trigger N
1bfa0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1bfb0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1bfc0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49  e SQLITE_DROP_VI
1bfd0 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37  EW            17
1bfe0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1bff0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1c000 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1c010 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20   SQLITE_INSERT  
1c020 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20               18 
1c030 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1c040 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1c050 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1c060 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20  SQLITE_PRAGMA   
1c070 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20              19  
1c080 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20   /* Pragma Name 
1c090 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e      1st arg or N
1c0a0 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ULL */.#define S
1c0b0 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20  QLITE_READ      
1c0c0 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20             20   
1c0d0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1c0e0 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
1c0f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1c100 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20  LITE_SELECT     
1c110 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f            21   /
1c120 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
1c130 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1c140 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1c150 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20  ITE_TRANSACTION 
1c160 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a           22   /*
1c170 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
1c180 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1c190 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1c1a0 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20  TE_UPDATE       
1c1b0 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
1c1c0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1c1d0 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
1c1e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1c1f0 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20  E_ATTACH        
1c200 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46         24   /* F
1c210 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e  ilename        N
1c220 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1c230 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1c240 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20  _DETACH         
1c250 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61        25   /* Da
1c260 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55  tabase Name   NU
1c270 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1c280 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c290 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20  ALTER_TABLE     
1c2a0 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74       26   /* Dat
1c2b0 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62  abase Name   Tab
1c2c0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1c2d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
1c2e0 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  EINDEX          
1c2f0 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65      27   /* Inde
1c300 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  x Name      NULL
1c310 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1c320 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
1c330 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20  ALYZE           
1c340 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65     28   /* Table
1c350 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1c360 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1c370 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1c380 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ATE_VTABLE      
1c390 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20    29   /* Table 
1c3a0 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
1c3b0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1c3c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1c3d0 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  _VTABLE         
1c3e0 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   30   /* Table N
1c3f0 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
1c400 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1c410 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54  ine SQLITE_FUNCT
1c420 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  ION             
1c430 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  31   /* NULL    
1c440 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e          Function
1c450 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69   Name   */.#defi
1c460 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f  ne SQLITE_SAVEPO
1c470 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33  INT            3
1c480 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
1c490 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74         Savepoint
1c4a0 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e   Name  */.#defin
1c4b0 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20  e SQLITE_COPY   
1c4c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
1c4d0 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20     /* No longer 
1c4e0 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
1c4f0 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67  API3REF: Tracing
1c500 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46   And Profiling F
1c510 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
1c520 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
1c530 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20  gister callback 
1c540 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63  functions that c
1c550 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a  an be used for.*
1c560 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72  * tracing and pr
1c570 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63  ofiling the exec
1c580 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61  ution of SQL sta
1c590 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
1c5a0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
1c5b0 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
1c5c0 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63   by sqlite3_trac
1c5d0 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  e() is invoked a
1c5e0 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d  t.** various tim
1c5f0 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73  es when an SQL s
1c600 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e  tatement is bein
1c610 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65  g run by [sqlite
1c620 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54  3_step()]..** ^T
1c630 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
1c640 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  () callback is i
1c650 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54  nvoked with a UT
1c660 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
1c670 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74   the.** SQL stat
1c680 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68  ement text as th
1c690 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  e statement firs
1c6a0 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69  t begins executi
1c6b0 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f  ng..** ^(Additio
1c6c0 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63  nal sqlite3_trac
1c6d0 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69  e() callbacks mi
1c6e0 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20  ght occur.** as 
1c6f0 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73  each triggered s
1c700 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74  ubprogram is ent
1c710 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62  ered.  The callb
1c720 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72  acks for trigger
1c730 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55  s.** contain a U
1c740 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  TF-8 SQL comment
1c750 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73   that identifies
1c760 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a   the trigger.)^.
1c770 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
1c780 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
1c790 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
1c7a0 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20  e3_profile() is 
1c7b0 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61  invoked.** as ea
1c7c0 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
1c7d0 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65   finishes.  ^The
1c7e0 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
1c7f0 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68  k contains.** th
1c800 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
1c810 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e  ment text and an
1c820 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c   estimate of wal
1c830 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20  l-clock time.** 
1c840 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74  of how long that
1c850 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20   statement took 
1c860 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72  to run.  ^The pr
1c870 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  ofile callback.*
1c880 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69  * time is in uni
1c890 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64  ts of nanosecond
1c8a0 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63  s, however the c
1c8b0 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  urrent implement
1c8c0 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79  ation.** is only
1c8d0 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c   capable of mill
1c8e0 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69  isecond resoluti
1c8f0 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65  on so the six le
1c900 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a  ast significant.
1c910 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65  ** digits in the
1c920 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e   time are meanin
1c930 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76  gless.  Future v
1c940 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
1c950 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69  e.** might provi
1c960 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c  de greater resol
1c970 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f  ution on the pro
1c980 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  filer callback. 
1c990 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
1c9a0 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69  profile() functi
1c9b0 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  on is considered
1c9c0 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
1c9d0 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20  d is.** subject 
1c9e0 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74  to change in fut
1c9f0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
1ca00 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20  SQLite..*/.void 
1ca10 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73  *sqlite3_trace(s
1ca20 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78  qlite3*, void(*x
1ca30 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  Trace)(void*,con
1ca40 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a  st char*), void*
1ca50 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49  );.SQLITE_EXPERI
1ca60 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c  MENTAL void *sql
1ca70 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c  ite3_profile(sql
1ca80 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a  ite3*,.   void(*
1ca90 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c  xProfile)(void*,
1caa0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69  const char*,sqli
1cab0 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69  te3_uint64), voi
1cac0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1cad0 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67  3REF: Query Prog
1cae0 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  ress Callbacks.*
1caf0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1cb00 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
1cb10 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65  er(D,N,X,P) inte
1cb20 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65  rface causes the
1cb30 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
1cb40 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e  ction X to be in
1cb50 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c  voked periodical
1cb60 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72  ly during long r
1cb70 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a  unning calls to.
1cb80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
1cb90 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
1cba0 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ep()] and [sqlit
1cbb0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
1cbc0 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  for.** database 
1cbd0 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41  connection D.  A
1cbe0 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f  n example use fo
1cbf0 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66  r this.** interf
1cc00 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61  ace is to keep a
1cc10 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72   GUI updated dur
1cc20 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72  ing a large quer
1cc30 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61  y..**.** ^The pa
1cc40 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 73  rameter P is pas
1cc50 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
1cc60 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
1cc70 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c  r to the .** cal
1cc80 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58  lback function X
1cc90 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  .  ^The paramete
1cca0 72 20 4e 20 69 73 20 74 68 65 20 6e 75 6d 62 65  r N is the numbe
1ccb0 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61  r of .** [virtua
1ccc0 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75  l machine instru
1ccd0 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65  ctions] that are
1cce0 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65   evaluated betwe
1ccf0 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a  en successive.**
1cd00 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
1cd10 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 0a  the callback X..
1cd20 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69  **.** ^Only a si
1cd30 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61  ngle progress ha
1cd40 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66  ndler may be def
1cd50 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65  ined at one time
1cd60 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73   per.** [databas
1cd70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73  e connection]; s
1cd80 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f  etting a new pro
1cd90 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
1cda0 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64  ncels the.** old
1cdb0 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20   one.  ^Setting 
1cdc0 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e  parameter X to N
1cdd0 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65  ULL disables the
1cde0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1cdf0 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72  r..** ^The progr
1ce00 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61  ess handler is a
1ce10 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20  lso disabled by 
1ce20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76  setting N to a v
1ce30 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61  alue less.** tha
1ce40 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  n 1..**.** ^If t
1ce50 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
1ce60 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
1ce70 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61  -zero, the opera
1ce80 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72  tion is.** inter
1ce90 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65  rupted.  This fe
1cea0 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65  ature can be use
1ceb0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
1cec0 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74  .** "Cancel" but
1ced0 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f  ton on a GUI pro
1cee0 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78  gress dialog box
1cef0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67  ..**.** The prog
1cf00 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c  ress handler cal
1cf10 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
1cf20 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
1cf30 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
1cf40 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1cf50 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
1cf60 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73  ked the progress
1cf70 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74   handler..** Not
1cf80 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
1cf90 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
1cfa0 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
1cfb0 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
1cfc0 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
1cfd0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
1cfe0 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
1cff0 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
1d000 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
1d010 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70  /.void sqlite3_p
1d020 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
1d030 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69  sqlite3*, int, i
1d040 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
1d050 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1d060 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41  I3REF: Opening A
1d070 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f   New Database Co
1d080 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e  nnection.**.** ^
1d090 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
1d0a0 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61  pen an SQLite da
1d0b0 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73  tabase file as s
1d0c0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
1d0d0 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  .** filename arg
1d0e0 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65  ument. ^The file
1d0f0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73  name argument is
1d100 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
1d110 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c  UTF-8 for.** sql
1d120 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
1d130 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1d140 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20  ) and as UTF-16 
1d150 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
1d160 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20  te.** order for 
1d170 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1d180 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20  . ^(A [database 
1d190 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
1d1a0 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a  le is usually.**
1d1b0 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70   returned in *pp
1d1c0 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65  Db, even if an e
1d1d0 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68  rror occurs.  Th
1d1e0 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e  e only exception
1d1f0 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53   is that.** if S
1d200 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
1d210 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
1d220 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b  ry to hold the [
1d230 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c  sqlite3] object,
1d240 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20  .** a NULL will 
1d250 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  be written into 
1d260 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66  *ppDb instead of
1d270 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
1d280 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f  e [sqlite3].** o
1d290 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68  bject.)^ ^(If th
1d2a0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1d2b0 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65  ened (and/or cre
1d2c0 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c  ated) successful
1d2d0 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c  ly, then.** [SQL
1d2e0 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
1d2f0 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
1d300 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
1d310 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e  is returned.)^ ^
1d320 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
1d330 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71  errmsg()] or [sq
1d340 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
1d350 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62  ] routines can b
1d360 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
1d370 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c  .** an English l
1d380 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74  anguage descript
1d390 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72  ion of the error
1d3a0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
1d3b0 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  lure of any.** o
1d3c0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  f the sqlite3_op
1d3d0 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  en() routines..*
1d3e0 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
1d3f0 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74  t encoding for t
1d400 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  he database will
1d410 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20   be UTF-8 if.** 
1d420 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
1d430 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
1d440 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e  2() is called an
1d450 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74  d.** UTF-16 in t
1d460 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
1d470 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f  rder if sqlite3_
1d480 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64  open16() is used
1d490 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20  ..**.** Whether 
1d4a0 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20  or not an error 
1d4b0 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69  occurs when it i
1d4c0 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72  s opened, resour
1d4d0 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ces.** associate
1d4e0 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  d with the [data
1d4f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1d500 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62   handle should b
1d510 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a  e released by.**
1d520 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
1d530 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
1d540 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c   when it is no l
1d550 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a  onger required..
1d560 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1d570 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65  3_open_v2() inte
1d580 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65  rface works like
1d590 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a   sqlite3_open().
1d5a0 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ** except that i
1d5b0 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64  t accepts two ad
1d5c0 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74  ditional paramet
1d5d0 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ers for addition
1d5e0 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76  al control.** ov
1d5f0 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  er the new datab
1d600 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  ase connection. 
1d610 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72   ^(The flags par
1d620 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c  ameter to.** sql
1d630 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63  ite3_open_v2() c
1d640 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a  an take one of.*
1d650 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * the following 
1d660 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70  three values, op
1d670 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
1d680 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b  d with the .** [
1d690 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
1d6a0 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
1d6b0 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b  EN_FULLMUTEX], [
1d6c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
1d6d0 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51  EDCACHE],.** [SQ
1d6e0 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
1d6f0 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20  ECACHE], and/or 
1d700 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
1d710 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a  ] flags:)^.**.**
1d720 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b   <dl>.** ^(<dt>[
1d730 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1d740 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ONLY]</dt>.** <d
1d750 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
1d760 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64  s opened in read
1d770 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20  -only mode.  If 
1d780 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65  the database doe
1d790 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79  s not.** already
1d7a0 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72   exist, an error
1d7b0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
1d7c0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
1d7d0 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
1d7e0 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  ADWRITE]</dt>.**
1d7f0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
1d800 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
1d810 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
1d820 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c  ing if possible,
1d830 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f   or reading.** o
1d840 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20  nly if the file 
1d850 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74  is write protect
1d860 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74  ed by the operat
1d870 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20  ing system.  In 
1d880 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74  either.** case t
1d890 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74  he database must
1d8a0 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
1d8b0 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72  otherwise an err
1d8c0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
1d8d0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
1d8e0 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
1d8f0 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
1d900 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
1d910 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
1d920 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1d930 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
1d940 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e   and writing, an
1d950 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a  d is created if.
1d960 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61  ** it does not a
1d970 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68  lready exist. Th
1d980 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69  is is the behavi
1d990 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79  or that is alway
1d9a0 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71  s used for.** sq
1d9b0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
1d9c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1d9d0 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  ).</dd>)^.** </d
1d9e0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  l>.**.** If the 
1d9f0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
1da00 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1da10 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  () is not one of
1da20 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74   the.** combinat
1da30 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  ions shown above
1da40 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
1da50 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a  ined with other.
1da60 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
1da70 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54  READONLY | SQLIT
1da80 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a  E_OPEN_* bits].*
1da90 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  * then the behav
1daa0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
1dab0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1dac0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
1dad0 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
1dae0 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  t, then the data
1daf0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1db00 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20  ** opens in the 
1db10 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  multi-thread [th
1db20 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73  reading mode] as
1db30 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e   long as the sin
1db40 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f  gle-thread.** mo
1db50 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  de has not been 
1db60 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
1db70 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
1db80 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b  e.  ^If the.** [
1db90 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
1dba0 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
1dbb0 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  et then the data
1dbc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1dbd0 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20  opens.** in the 
1dbe0 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
1dbf0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65  ading mode] unle
1dc00 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  ss single-thread
1dc10 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73   was.** previous
1dc20 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63  ly selected at c
1dc30 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
1dc40 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54  tart-time..** ^T
1dc50 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
1dc60 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61  SHAREDCACHE] fla
1dc70 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
1dc80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1dc90 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62   to be.** eligib
1dca0 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65  le to use [share
1dcb0 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72  d cache mode], r
1dcc0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
1dcd0 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
1dce0 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65  ed.** cache is e
1dcf0 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71  nabled using [sq
1dd00 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
1dd10 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e  red_cache()].  ^
1dd20 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  The.** [SQLITE_O
1dd30 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
1dd40 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
1dd50 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1dd60 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20  ction to not.** 
1dd70 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b  participate in [
1dd80 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
1dd90 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  e] even if it is
1dda0 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
1ddb0 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
1ddc0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1ddd0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68  _open_v2() is th
1dde0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a  e name of the.**
1ddf0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
1de00 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
1de10 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
1de20 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
1de30 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65  e that.** the ne
1de40 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
1de50 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65  ction should use
1de60 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74  .  ^If the fourt
1de70 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
1de80 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
1de90 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c   then the defaul
1dea0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
1deb0 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a  object is used..
1dec0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
1ded0 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f  lename is ":memo
1dee0 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69  ry:", then a pri
1def0 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20  vate, temporary 
1df00 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
1df10 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64  se.** is created
1df20 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74   for the connect
1df30 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d  ion.  ^This in-m
1df40 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77  emory database w
1df50 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a  ill vanish when.
1df60 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
1df70 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
1df80 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65  osed.  Future ve
1df90 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1dfa0 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75   might.** make u
1dfb0 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c  se of additional
1dfc0 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d   special filenam
1dfd0 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69  es that begin wi
1dfe0 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61  th the ":" chara
1dff0 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72  cter..** It is r
1e000 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
1e010 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  when a database 
1e020 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c  filename actuall
1e030 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74  y does begin wit
1e040 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61  h.** a ":" chara
1e050 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20  cter you should 
1e060 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e  prefix the filen
1e070 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e  ame with a pathn
1e080 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22  ame such as.** "
1e090 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62  ./" to avoid amb
1e0a0 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iguity..**.** ^I
1e0b0 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
1e0c0 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  s an empty strin
1e0d0 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  g, then a privat
1e0e0 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20  e, temporary.** 
1e0f0 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65  on-disk database
1e100 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64   will be created
1e110 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65  .  ^This private
1e120 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
1e130 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  e.** automatical
1e140 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f  ly deleted as so
1e150 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61  on as the databa
1e160 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
1e170 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b   closed..**.** [
1e180 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69  [URI filenames i
1e190 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  n sqlite3_open()
1e1a0 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e  ]] <h3>URI Filen
1e1b0 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ames</h3>.**.** 
1e1c0 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ^If [URI filenam
1e1d0 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  e] interpretatio
1e1e0 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e  n is enabled, an
1e1f0 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  d the filename a
1e200 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e  rgument.** begin
1e210 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20  s with "file:", 
1e220 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d  then the filenam
1e230 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  e is interpreted
1e240 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a   as a URI. ^URI.
1e250 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65  ** filename inte
1e260 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e  rpretation is en
1e270 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51  abled if the [SQ
1e280 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
1e290 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e  lag is.** set in
1e2a0 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
1e2b0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
1e2c0 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66  open_v2(), or if
1e2d0 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20   it has.** been 
1e2e0 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79  enabled globally
1e2f0 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49   using the [SQLI
1e300 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f  TE_CONFIG_URI] o
1e310 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a  ption with the.*
1e320 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
1e330 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62  g()] method or b
1e340 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53  y the [SQLITE_US
1e350 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74  E_URI] compile-t
1e360 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41  ime option..** A
1e370 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73  s of SQLite vers
1e380 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66  ion 3.7.7, URI f
1e390 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
1e3a0 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  tation is turned
1e3b0 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75   off.** by defau
1e3c0 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72  lt, but future r
1e3d0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
1e3e0 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55  e might enable U
1e3f0 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69  RI filename.** i
1e400 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79  nterpretation by
1e410 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22   default.  See "
1e420 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22  [URI filenames]"
1e430 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
1e440 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
1e450 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61  **.** URI filena
1e460 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61  mes are parsed a
1e470 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20  ccording to RFC 
1e480 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52  3986. ^If the UR
1e490 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a  I contains an.**
1e4a0 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e   authority, then
1e4b0 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68   it must be eith
1e4c0 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  er an empty stri
1e4d0 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67  ng or the string
1e4e0 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22   .** "localhost"
1e4f0 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72  . ^If the author
1e500 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d  ity is not an em
1e510 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c  pty string or "l
1e520 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a  ocalhost", an .*
1e530 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  * error is retur
1e540 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65  ned to the calle
1e550 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74  r. ^The fragment
1e560 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
1e570 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73  URI, if .** pres
1e580 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e  ent, is ignored.
1e590 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
1e5a0 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d  ses the path com
1e5b0 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52  ponent of the UR
1e5c0 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  I as the name of
1e5d0 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a   the disk file.*
1e5e0 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73  * which contains
1e5f0 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e   the database. ^
1e600 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69  If the path begi
1e610 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68  ns with a '/' ch
1e620 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65  aracter, .** the
1e630 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65  n it is interpre
1e640 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75  ted as an absolu
1e650 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65  te path. ^If the
1e660 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62   path does not b
1e670 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20  egin .** with a 
1e680 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61  '/' (meaning tha
1e690 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  t the authority 
1e6a0 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74  section is omitt
1e6b0 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29  ed from the URI)
1e6c0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74  .** then the pat
1e6d0 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
1e6e0 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70   as a relative p
1e6f0 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e  ath. .** ^On win
1e700 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20  dows, the first 
1e710 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20  component of an 
1e720 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a  absolute path .*
1e730 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65  * is a drive spe
1e740 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e  cification (e.g.
1e750 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b   "C:")..**.** [[
1e760 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70  core URI query p
1e770 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54  arameters]].** T
1e780 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  he query compone
1e790 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20  nt of a URI may 
1e7a0 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65  contain paramete
1e7b0 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  rs that are inte
1e7c0 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65  rpreted.** eithe
1e7d0 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65  r by SQLite itse
1e7e0 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53  lf, or by a [VFS
1e7f0 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d   | custom VFS im
1e800 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a  plementation]..*
1e810 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72  * SQLite interpr
1e820 65 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  ets the followin
1e830 67 20 74 68 72 65 65 20 71 75 65 72 79 20 70 61  g three query pa
1e840 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20  rameters:.**.** 
1e850 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  <ul>.**   <li> <
1e860 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20  b>vfs</b>: ^The 
1e870 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20  "vfs" parameter 
1e880 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73  may be used to s
1e890 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20  pecify the name 
1e8a0 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20  of.**     a VFS 
1e8b0 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76  object that prov
1e8c0 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ides the operati
1e8d0 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
1e8e0 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a  ace that should.
1e8f0 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74  **     be used t
1e900 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  o access the dat
1e910 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69  abase file on di
1e920 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74  sk. ^If this opt
1e930 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a  ion is set to.**
1e940 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74       an empty st
1e950 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74  ring the default
1e960 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75   VFS object is u
1e970 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67  sed. ^Specifying
1e980 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20   an unknown.**  
1e990 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72     VFS is an err
1e9a0 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  or. ^If sqlite3_
1e9b0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65  open_v2() is use
1e9c0 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70  d and the vfs op
1e9d0 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70  tion is.**     p
1e9e0 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65  resent, then the
1e9f0 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62   VFS specified b
1ea00 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b  y the option tak
1ea10 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76  es precedence ov
1ea20 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61  er.**     the va
1ea30 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
1ea40 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
1ea50 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
1ea60 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20  en_v2()..**.**  
1ea70 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62   <li> <b>mode</b
1ea80 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61  >: ^(The mode pa
1ea90 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
1eaa0 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f  et to either "ro
1eab0 22 2c 20 22 72 77 22 20 6f 72 0a 2a 2a 20 20 20  ", "rw" or.**   
1eac0 20 20 22 72 77 63 22 2e 20 41 74 74 65 6d 70 74    "rwc". Attempt
1ead0 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f  ing to set it to
1eae0 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65   any other value
1eaf0 20 69 73 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20   is an error)^. 
1eb00 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22  .**     ^If "ro"
1eb10 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74   is specified, t
1eb20 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
1eb30 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
1eb40 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20  ead-only .**    
1eb50 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73   access, just as
1eb60 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
1eb70 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66  OPEN_READONLY] f
1eb80 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74  lag had been set
1eb90 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20   in the .**     
1eba0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
1ebb0 6f 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  o sqlite3_prepar
1ebc0 65 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20  e_v2(). ^If the 
1ebd0 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73  mode option is s
1ebe0 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72  et to .**     "r
1ebf0 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  w", then the dat
1ec00 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1ec10 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28  for read-write (
1ec20 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20  but not create) 
1ec30 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20  .**     access, 
1ec40 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45  as if SQLITE_OPE
1ec50 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74  N_READWRITE (but
1ec60 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e   not SQLITE_OPEN
1ec70 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a  _CREATE) had .**
1ec80 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e       been set. ^
1ec90 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65  Value "rwc" is e
1eca0 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
1ecb0 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20  ting both .**   
1ecc0 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45    SQLITE_OPEN_RE
1ecd0 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49  ADWRITE and SQLI
1ece0 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20  TE_OPEN_CREATE. 
1ecf0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
1ed00 5f 76 32 28 29 20 69 73 20 0a 2a 2a 20 20 20 20  _v2() is .**    
1ed10 20 75 73 65 64 2c 20 69 74 20 69 73 20 61 6e 20   used, it is an 
1ed20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79  error to specify
1ed30 20 61 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65   a value for the
1ed40 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20   mode parameter 
1ed50 74 68 61 74 20 69 73 20 0a 2a 2a 20 20 20 20 20  that is .**     
1ed60 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65  less restrictive
1ed70 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69   than that speci
1ed80 66 69 65 64 20 62 79 20 74 68 65 20 66 6c 61 67  fied by the flag
1ed90 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  s passed as the 
1eda0 74 68 69 72 64 20 0a 2a 2a 20 20 20 20 20 70 61  third .**     pa
1edb0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 20  rameter..**.**  
1edc0 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f   <li> <b>cache</
1edd0 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70  b>: ^The cache p
1ede0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
1edf0 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73  set to either "s
1ee00 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20  hared" or.**    
1ee10 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74   "private". ^Set
1ee20 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72  ting it to "shar
1ee30 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e  ed" is equivalen
1ee40 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65  t to setting the
1ee50 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
1ee60 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
1ee70 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73  bit in the flags
1ee80 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
1ee90 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74   to.**     sqlit
1eea0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53  e3_open_v2(). ^S
1eeb0 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65  etting the cache
1eec0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70   parameter to "p
1eed0 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20  rivate" is .**  
1eee0 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f     equivalent to
1eef0 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c   setting the SQL
1ef00 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
1ef10 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20  CACHE bit..**   
1ef20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70    ^If sqlite3_op
1ef30 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
1ef40 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20  and the "cache" 
1ef50 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65  parameter is pre
1ef60 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61  sent in.**     a
1ef70 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69   URI filename, i
1ef80 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64  ts value overrid
1ef90 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 75 72  es any behaviour
1efa0 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65   requested by se
1efb0 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c  tting.**     SQL
1efc0 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
1efd0 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f  CACHE or SQLITE_
1efe0 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
1eff0 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a   flag..** </ul>.
1f000 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e  **.** ^Specifyin
1f010 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72  g an unknown par
1f020 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75  ameter in the qu
1f030 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ery component of
1f040 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e   a URI is not an
1f050 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75  .** error.  Futu
1f060 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1f070 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65  QLite might unde
1f080 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61  rstand additiona
1f090 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d  l query.** param
1f0a0 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75  eters.  See "[qu
1f0b0 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77  ery parameters w
1f0c0 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e  ith special mean
1f0d0 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20  ing to SQLite]" 
1f0e0 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
1f0f0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
1f100 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e  *.** [[URI filen
1f110 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c  ame examples]] <
1f120 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  h3>URI filename 
1f130 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a  examples</h3>.**
1f140 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
1f150 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74  r="1" align=cent
1f160 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35  er cellpadding=5
1f170 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52  >.** <tr><th> UR
1f180 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e  I filenames <th>
1f190 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e   Results.** <tr>
1f1a0 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
1f1b0 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
1f1c0 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c      Open the fil
1f1d0 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
1f1e0 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
1f1f0 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tory..** <tr><td
1f200 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
1f210 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a  d/data.db<br>.**
1f220 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
1f230 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  //home/fred/data
1f240 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20  .db <br> .**    
1f250 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63        file://loc
1f260 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64  alhost/home/fred
1f270 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74  /data.db <br> <t
1f280 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
1f290 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  Open the databas
1f2a0 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72  e file "/home/fr
1f2b0 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20  ed/data.db"..** 
1f2c0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f  <tr><td> file://
1f2d0 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72  darkstar/home/fr
1f2e0 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  ed/data.db <td> 
1f2f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20  .**          An 
1f300 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72  error. "darkstar
1f310 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67  " is not a recog
1f320 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e  nized authority.
1f330 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c  .** <tr><td styl
1f340 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e  e="white-space:n
1f350 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20  owrap"> .**     
1f360 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f       file:///C:/
1f370 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25  Documents%20and%
1f380 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f  20Settings/fred/
1f390 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a  Desktop/data.db.
1f3a0 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64  **     <td> Wind
1f3b0 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74  ows only: Open t
1f3c0 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  he file "data.db
1f3d0 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b  " on fred's desk
1f3e0 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20  top on drive.** 
1f3f0 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74           C:. Not
1f400 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65  e that the %20 e
1f410 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20  scaping in this 
1f420 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73  example is not s
1f430 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20  trictly .**     
1f440 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d       necessary -
1f450 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72   space character
1f460 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69  s can be used li
1f470 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20  terally.**      
1f480 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e      in URI filen
1f490 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ames..** <tr><td
1f4a0 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
1f4b0 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69  ode=ro&cache=pri
1f4c0 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  vate <td> .**   
1f4d0 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
1f4e0 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68   "data.db" in th
1f4f0 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74  e current direct
1f500 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ory for read-onl
1f510 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20  y access..**    
1f520 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73        Regardless
1f530 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
1f540 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20  ot shared-cache 
1f550 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20  mode is enabled 
1f560 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  by.**          d
1f570 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72  efault, use a pr
1f580 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20  ivate cache..** 
1f590 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
1f5a0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
1f5b0 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b  ?vfs=unix-nolock
1f5c0 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20   <td>.**        
1f5d0 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f    Open file "/ho
1f5e0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22  me/fred/data.db"
1f5f0 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61  . Use the specia
1f600 6c 20 56 46 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f  l VFS "unix-nolo
1f610 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ck"..** <tr><td>
1f620 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f   file:data.db?mo
1f630 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e  de=readonly <td>
1f640 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e   .**          An
1f650 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c   error. "readonl
1f660 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69  y" is not a vali
1f670 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65  d option for the
1f680 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65   "mode" paramete
1f690 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  r..** </table>.*
1f6a0 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65  *.** ^URI hexade
1f6b0 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
1f6c0 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 65  uences (%HH) are
1f6d0 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 69   supported withi
1f6e0 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a  n the path and.*
1f6f0 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  * query componen
1f700 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68  ts of a URI. A h
1f710 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
1f720 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69  e sequence consi
1f730 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63  sts of a.** perc
1f740 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d  ent sign - "%" -
1f750 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61   followed by exa
1f760 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63  ctly two hexadec
1f770 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20  imal digits .** 
1f780 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63  specifying an oc
1f790 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f  tet value. ^Befo
1f7a0 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 71  re the path or q
1f7b0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
1f7c0 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65  of a.** URI file
1f7d0 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72  name are interpr
1f7e0 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 65  eted, they are e
1f7f0 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46  ncoded using UTF
1f800 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68  -8 and all .** h
1f810 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
1f820 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c  e sequences repl
1f830 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65  aced by a single
1f840 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67   byte containing
1f850 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f   the.** correspo
1f860 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20  nding octet. If 
1f870 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e  this process gen
1f880 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69  erates an invali
1f890 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  d UTF-8 encoding
1f8a0 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73  ,.** the results
1f8b0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
1f8c0 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
1f8d0 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c   Windows users:<
1f8e0 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e  /b>  The encodin
1f8f0 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66  g used for the f
1f900 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
1f910 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  .** of sqlite3_o
1f920 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
1f930 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74  3_open_v2() must
1f940 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77   be UTF-8, not w
1f950 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70  hatever.** codep
1f960 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79  age is currently
1f970 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e   defined.  Filen
1f980 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ames containing 
1f990 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a  international.**
1f9a0 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74   characters must
1f9b0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   be converted to
1f9c0 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20   UTF-8 prior to 
1f9d0 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74  passing them int
1f9e0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
1f9f0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
1fa00 70 65 6e 5f 76 32 28 29 2e 0a 2a 2f 0a 69 6e 74  pen_v2()..*/.int
1fa10 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20   sqlite3_open(. 
1fa20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
1fa30 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
1fa40 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
1fa50 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
1fa60 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
1fa70 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
1fa80 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
1fa90 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  ;.int sqlite3_op
1faa0 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f  en16(.  const vo
1fab0 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  id *filename,   
1fac0 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
1fad0 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f  name (UTF-16) */
1fae0 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
1faf0 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
1fb00 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
1fb10 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  dle */.);.int sq
1fb20 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20  lite3_open_v2(. 
1fb30 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
1fb40 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
1fb50 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
1fb60 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
1fb70 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20  e3 **ppDb,      
1fb80 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
1fb90 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  e db handle */. 
1fba0 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20   int flags,     
1fbb0 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67           /* Flag
1fbc0 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  s */.  const cha
1fbd0 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f  r *zVfs        /
1fbe0 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f  * Name of VFS mo
1fbf0 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29  dule to use */.)
1fc00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1fc10 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73  F: Obtain Values
1fc20 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74   For URI Paramet
1fc30 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ers.**.** These 
1fc40 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74  are utility rout
1fc50 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20  ines, useful to 
1fc60 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
1fc70 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a  ons, that check.
1fc80 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64  ** to see if a d
1fc90 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73  atabase file was
1fca0 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74   a URI that cont
1fcb0 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63  ained a specific
1fcc0 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d   query .** param
1fcd0 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20  eter, and if so 
1fce0 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75  obtains the valu
1fcf0 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 20  e of that query 
1fd00 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
1fd10 20 49 66 20 46 20 69 73 20 74 68 65 20 66 69 6c   If F is the fil
1fd20 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61  ename pointer pa
1fd30 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f  ssed into the xO
1fd40 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20  pen() method of 
1fd50 61 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65  a VFS.** impleme
1fd60 6e 74 61 74 69 6f 6e 20 61 6e 64 20 50 20 69 73  ntation and P is
1fd70 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1fd80 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
1fd90 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
1fda0 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
1fdb0 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 65  F,P) returns the
1fdc0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a   value of the P.
1fdd0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20  ** parameter if 
1fde0 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e  it exists or a N
1fdf0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50  ULL pointer if P
1fe00 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72   does not appear
1fe10 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20   as a .** query 
1fe20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20  parameter on F. 
1fe30 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72 79   If P is a query
1fe40 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a   parameter of F.
1fe50 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63  ** has no explic
1fe60 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73  it value, then s
1fe70 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
1fe80 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
1fe90 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
1fea0 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  o an empty strin
1feb0 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  g..**.** The sql
1fec0 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
1fed0 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20  (F,P,B) routine 
1fee0 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 69  assumes that P i
1fef0 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70  s a boolean.** p
1ff00 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
1ff10 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72  urns true (1) or
1ff20 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72   false (0) accor
1ff30 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75  ding to the valu
1ff40 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20  e.** of P.  The 
1ff50 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 74 72  value of P is tr
1ff60 75 65 20 69 66 20 69 74 20 69 73 20 22 79 65 73  ue if it is "yes
1ff70 22 20 6f 72 20 22 74 72 75 65 22 20 6f 72 20 22  " or "true" or "
1ff80 6f 6e 22 20 6f 72 20 0a 2a 2a 20 61 20 6e 6f 6e  on" or .** a non
1ff90 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 20 61 6e 64  -zero number and
1ffa0 20 69 73 20 66 61 6c 73 65 20 6f 74 68 65 72 77   is false otherw
1ffb0 69 73 65 2e 20 20 49 66 20 50 20 69 73 20 6e 6f  ise.  If P is no
1ffc0 74 20 61 20 71 75 65 72 79 20 70 61 72 61 6d 65  t a query parame
1ffd0 74 65 72 0a 2a 2a 20 6f 6e 20 46 20 74 68 65 6e  ter.** on F then
1ffe0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
1fff0 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75  lean(F,P,B) retu
20000 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a  rns (B!=0)..**.*
20010 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72  * The sqlite3_ur
20020 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72  i_int64(F,P,D) r
20030 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20  outine converts 
20040 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
20050 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20  nto a.** 64-bit 
20060 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61  signed integer a
20070 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 20  nd returns that 
20080 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66  integer, or D if
20090 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65   P does not.** e
200a0 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 61  xist.  If the va
200b0 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65  lue of P is some
200c0 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
200d0 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65   an integer, the
200e0 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74  n.** zero is ret
200f0 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66  urned..** .** If
20100 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   F is a NULL poi
20110 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74  nter, then sqlit
20120 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
20130 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55  (F,P) returns NU
20140 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  LL and.** sqlite
20150 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
20160 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20  P,B) returns B. 
20170 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e   If F is not a N
20180 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a  ULL pointer and.
20190 2a 2a 20 69 73 20 6e 6f 74 20 61 20 70 61 74 68  ** is not a path
201a0 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61  name pointer tha
201b0 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20  t SQLite passed 
201c0 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 56  into the xOpen V
201d0 46 53 20 6d 65 74 68 6f 64 2c 0a 2a 2a 20 74 68  FS method,.** th
201e0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
201f0 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  of this routine 
20200 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
20210 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69   probably undesi
20220 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  rable..*/.const 
20230 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72  char *sqlite3_ur
20240 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73  i_parameter(cons
20250 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d  t char *zFilenam
20260 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  e, const char *z
20270 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69  Param);.int sqli
20280 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
20290 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
202a0 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  e, const char *z
202b0 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61  Param, int bDefa
202c0 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  ult);.sqlite3_in
202d0 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  t64 sqlite3_uri_
202e0 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72  int64(const char
202f0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
20300 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
20310 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20320 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e  : Error Codes An
20330 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a  d Messages.**.**
20340 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
20350 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63  rcode() interfac
20360 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
20370 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f  meric [result co
20380 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  de] or.** [exten
20390 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
203a0 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65   for the most re
203b0 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69  cent failed sqli
203c0 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a  te3_* API call.*
203d0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
203e0 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
203f0 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20  nnection]. If a 
20400 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66  prior API call f
20410 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65  ailed.** but the
20420 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49   most recent API
20430 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c   call succeeded,
20440 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
20450 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  e from.** sqlite
20460 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75  3_errcode() is u
20470 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  ndefined.  ^The 
20480 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
20490 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e  _errcode().** in
204a0 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73  terface is the s
204b0 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20  ame except that 
204c0 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
204d0 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e  s the .** [exten
204e0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
204f0 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e   even when exten
20500 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
20510 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64   are.** disabled
20520 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
20530 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e  ite3_errmsg() an
20540 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  d sqlite3_errmsg
20550 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c  16() return Engl
20560 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20  ish-language.** 
20570 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69  text that descri
20580 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61  bes the error, a
20590 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
205a0 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74  r UTF-16 respect
205b0 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  ively..** ^(Memo
205c0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
205d0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
205e0 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
205f0 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68  nternally..** Th
20600 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
20610 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77  es not need to w
20620 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69  orry about freei
20630 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  ng the result..*
20640 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65  * However, the e
20650 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68  rror string migh
20660 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  t be overwritten
20670 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   or deallocated 
20680 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  by.** subsequent
20690 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20   calls to other 
206a0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
206b0 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a   functions.)^.**
206c0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72  .** When the ser
206d0 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
206e0 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75  ng mode] is in u
206f0 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20  se, it might be 
20700 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74  the.** case that
20710 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20   a second error 
20720 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61  occurs on a sepa
20730 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62  rate thread in b
20740 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69  etween.** the ti
20750 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  me of the first 
20760 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61  error and the ca
20770 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  ll to these inte
20780 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20  rfaces..** When 
20790 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68  that happens, th
207a0 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77  e second error w
207b0 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20  ill be reported 
207c0 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69  since these.** i
207d0 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73  nterfaces always
207e0 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74   report the most
207f0 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20   recent result. 
20800 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69   To avoid.** thi
20810 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63  s, each thread c
20820 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73  an obtain exclus
20830 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  ive use of the [
20840 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
20850 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76  ion] D.** by inv
20860 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
20870 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c  utex_enter]([sql
20880 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
20890 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e  )) before beginn
208a0 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20  ing.** to use D 
208b0 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71  and invoking [sq
208c0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
208d0 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  e]([sqlite3_db_m
208e0 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a  utex](D)) after.
208f0 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20  ** all calls to 
20900 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c  the interfaces l
20910 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63  isted here are c
20920 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ompleted..**.** 
20930 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20  If an interface 
20940 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54  fails with SQLIT
20950 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d  E_MISUSE, that m
20960 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61  eans the interfa
20970 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65  ce.** was invoke
20980 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79  d incorrectly by
20990 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
209a0 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c  .  In that case,
209b0 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f   the.** error co
209c0 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d  de and message m
209d0 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65  ay or may not be
209e0 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c   set..*/.int sql
209f0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c  ite3_errcode(sql
20a00 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73  ite3 *db);.int s
20a10 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
20a20 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
20a30 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  *db);.const char
20a40 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
20a50 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73  (sqlite3*);.cons
20a60 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
20a70 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33  errmsg16(sqlite3
20a80 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
20a90 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65  REF: SQL Stateme
20aa0 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  nt Object.** KEY
20ab0 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64  WORDS: {prepared
20ac0 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65   statement} {pre
20ad0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
20ae0 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
20af0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
20b00 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20  ct represents a 
20b10 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
20b20 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ment..** This ob
20b30 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c  ject is variousl
20b40 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72  y known as a "pr
20b50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
20b60 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69  " or a.** "compi
20b70 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  led SQL statemen
20b80 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20  t" or simply as 
20b90 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a  a "statement"..*
20ba0 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66  *.** The life of
20bb0 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a   a statement obj
20bc0 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69  ect goes somethi
20bd0 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ng like this:.**
20be0 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
20bf0 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65   Create the obje
20c00 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
20c10 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
20c20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20  or a related.** 
20c30 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a       function..*
20c40 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75  * <li> Bind valu
20c50 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61  es to [host para
20c60 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68  meters] using th
20c70 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
20c80 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72  ().**      inter
20c90 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  faces..** <li> R
20ca0 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61  un the SQL by ca
20cb0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  lling [sqlite3_s
20cc0 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f  tep()] one or mo
20cd0 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
20ce0 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74  > Reset the stat
20cf0 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
20d00 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68  ite3_reset()] th
20d10 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20  en go back.**   
20d20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44     to step 2.  D
20d30 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d  o this zero or m
20d40 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
20d50 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f  i> Destroy the o
20d60 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
20d70 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
20d80 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  ..** </ol>.**.**
20d90 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65   Refer to docume
20da0 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  ntation on indiv
20db0 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62  idual methods ab
20dc0 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ove for addition
20dd0 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
20de0 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
20df0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  ruct sqlite3_stm
20e00 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a  t sqlite3_stmt;.
20e10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
20e20 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73   Run-time Limits
20e30 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e  .**.** ^(This in
20e40 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74  terface allows t
20e50 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f  he size of vario
20e60 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  us constructs to
20e70 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f   be limited.** o
20e80 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  n a connection b
20e90 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  y connection bas
20ea0 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  is.  The first p
20eb0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
20ec0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
20ed0 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c  nection] whose l
20ee0 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65  imit is to be se
20ef0 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54  t or queried.  T
20f00 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
20f10 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66  ameter is one of
20f20 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65   the [limit cate
20f30 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66  gories] that def
20f40 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f  ine a.** class o
20f50 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  f constructs to 
20f60 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e  be size limited.
20f70 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61    The third para
20f80 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
20f90 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68  new limit for th
20fa0 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a  at construct.)^.
20fb0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65  **.** ^If the ne
20fc0 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67  w limit is a neg
20fd0 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68  ative number, th
20fe0 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61  e limit is uncha
20ff0 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65  nged..** ^(For e
21000 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ach limit catego
21010 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ry SQLITE_LIMIT_
21020 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72  <i>NAME</i> ther
21030 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69  e is a .** [limi
21040 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20  ts | hard upper 
21050 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74  bound].** set at
21060 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79   compile-time by
21070 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f   a C preprocesso
21080 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a  r macro called.*
21090 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49  * [limits | SQLI
210a0 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f  TE_MAX_<i>NAME</
210b0 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c  i>]..** (The "_L
210c0 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61  IMIT_" in the na
210d0 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f  me is changed to
210e0 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20   "_MAX_".))^.** 
210f0 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63  ^Attempts to inc
21100 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62  rease a limit ab
21110 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70  ove its hard upp
21120 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20  er bound are.** 
21130 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74  silently truncat
21140 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75  ed to the hard u
21150 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a  pper bound..**.*
21160 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66  * ^Regardless of
21170 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
21180 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68  the limit was ch
21190 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b  anged, the .** [
211a0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
211b0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
211c0 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c  ns the prior val
211d0 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e  ue of the limit.
211e0 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66  .** ^Hence, to f
211f0 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20  ind the current 
21200 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74  value of a limit
21210 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e   without changin
21220 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20  g it,.** simply 
21230 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65  invoke this inte
21240 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20 74  rface with the t
21250 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 73  hird parameter s
21260 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20  et to -1..**.** 
21270 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20  Run-time limits 
21280 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
21290 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74   use in applicat
212a0 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65  ions that manage
212b0 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f  .** both their o
212c0 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  wn internal data
212d0 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61  base and also da
212e0 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65  tabases that are
212f0 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62   controlled.** b
21300 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65  y untrusted exte
21310 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41  rnal sources.  A
21320 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63  n example applic
21330 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61  ation might be a
21340 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20  .** web browser 
21350 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e  that has its own
21360 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73   databases for s
21370 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61  toring history a
21380 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64  nd.** separate d
21390 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c  atabases control
213a0 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70  led by JavaScrip
213b0 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64  t applications d
213c0 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66  ownloaded.** off
213d0 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20   the Internet.  
213e0 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  The internal dat
213f0 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69  abases can be gi
21400 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65  ven the.** large
21410 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73  , default limits
21420 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e  .  Databases man
21430 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c  aged by external
21440 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20   sources can.** 
21450 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d  be given much sm
21460 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73  aller limits des
21470 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74  igned to prevent
21480 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72   a denial of ser
21490 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20  vice.** attack. 
214a0 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68   Developers migh
214b0 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75  t also want to u
214c0 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
214d0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
214e0 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74  ].** interface t
214f0 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f  o further contro
21500 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e  l untrusted SQL.
21510 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
21520 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72  e database.** cr
21530 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72  eated by an untr
21540 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e  usted script can
21550 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73   be contained us
21560 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f  ing the.** [max_
21570 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
21580 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  GMA]..**.** New 
21590 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63  run-time limit c
215a0 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65  ategories may be
215b0 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
215c0 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e   releases..*/.in
215d0 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28  t sqlite3_limit(
215e0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64  sqlite3*, int id
215f0 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a  , int newVal);..
21600 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
21610 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43  Run-Time Limit C
21620 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59  ategories.** KEY
21630 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61  WORDS: {limit ca
21640 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20  tegory} {*limit 
21650 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a  categories}.**.*
21660 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
21670 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73  s define various
21680 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d   performance lim
21690 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  its.** that can 
216a0 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75  be lowered at ru
216b0 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71  n-time using [sq
216c0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a  lite3_limit()]..
216d0 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20  ** The synopsis 
216e0 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20  of the meanings 
216f0 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c  of the various l
21700 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62  imits is shown b
21710 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f  elow..** Additio
21720 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  nal information 
21730 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20  is available at 
21740 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73  [limits | Limits
21750 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a   in SQLite]..**.
21760 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
21770 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
21780 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
21790 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74  LIMIT_LENGTH</dt
217a0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
217b0 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79  imum size of any
217c0 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
217d0 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e  or table row, in
217e0 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a   bytes.<dd>)^.**
217f0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
21800 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20  IT_SQL_LENGTH]] 
21810 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
21820 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64  IT_SQL_LENGTH</d
21830 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
21840 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
21850 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
21860 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e  , in bytes.</dd>
21870 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
21880 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d  E_LIMIT_COLUMN]]
21890 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
218a0 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a  MIT_COLUMN</dt>.
218b0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
218c0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
218d0 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20  umns in a table 
218e0 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e  definition or in
218f0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73   the.** result s
21900 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
21910 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   or the maximum 
21920 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
21930 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a  s in an index.**
21940 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20   or in an ORDER 
21950 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63  BY or GROUP BY c
21960 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  lause.</dd>)^.**
21970 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
21980 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20  IT_EXPR_DEPTH]] 
21990 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
219a0 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64  IT_EXPR_DEPTH</d
219b0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
219c0 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74  ximum depth of t
219d0 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e  he parse tree on
219e0 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e   any expression.
219f0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
21a00 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
21a10 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e  POUND_SELECT]] ^
21a20 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
21a30 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
21a40 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  T</dt>.** <dd>Th
21a50 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
21a60 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63   of terms in a c
21a70 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73  ompound SELECT s
21a80 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e  tatement.</dd>)^
21a90 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
21aa0 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20  LIMIT_VDBE_OP]] 
21ab0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
21ac0 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a  IT_VDBE_OP</dt>.
21ad0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
21ae0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73  um number of ins
21af0 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76  tructions in a v
21b00 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70  irtual machine p
21b10 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74  rogram.** used t
21b20 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53  o implement an S
21b30 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54  QL statement.  T
21b40 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74  his limit is not
21b50 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e   currently.** en
21b60 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74  forced, though t
21b70 68 61 74 20 6d 69 67 68 74 20 62 65 20 61 64 64  hat might be add
21b80 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72  ed in some futur
21b90 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20  e release of.** 
21ba0 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a  SQLite.</dd>)^.*
21bb0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
21bc0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
21bd0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
21be0 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
21bf0 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  RG</dt>.** <dd>T
21c00 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
21c10 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f  r of arguments o
21c20 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64  n a function.</d
21c30 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
21c40 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
21c50 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ED]] ^(<dt>SQLIT
21c60 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
21c70 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
21c80 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
21c90 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74  of [ATTACH | att
21ca0 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d  ached databases]
21cb0 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  .)^</dd>.**.** [
21cc0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49  [SQLITE_LIMIT_LI
21cd0 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
21ce0 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  H]].** ^(<dt>SQL
21cf0 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
21d00 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64  ATTERN_LENGTH</d
21d10 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
21d20 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
21d30 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75  the pattern argu
21d40 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b  ment to the [LIK
21d50 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20  E] or.** [GLOB] 
21d60 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29  operators.</dd>)
21d70 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
21d80 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
21d90 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64  NUMBER]].** ^(<d
21da0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
21db0 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f  ARIABLE_NUMBER</
21dc0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
21dd0 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d  aximum index num
21de0 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61  ber of any [para
21df0 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c  meter] in an SQL
21e00 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a   statement.)^.**
21e10 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
21e20 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
21e30 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
21e40 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
21e50 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
21e60 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
21e70 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66  h of recursion f
21e80 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64  or triggers.</dd
21e90 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  >)^.** </dl>.*/.
21ea0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
21eb0 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20  IMIT_LENGTH     
21ec0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
21ed0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21ee0 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
21ef0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
21f00 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
21f10 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20  _LIMIT_COLUMN   
21f20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
21f30 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
21f40 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
21f50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
21f60 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
21f70 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
21f80 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  D_SELECT        
21f90 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
21fa0 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
21fb0 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  P               
21fc0 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
21fd0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
21fe0 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20  ION_ARG         
21ff0 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
22000 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
22010 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20  CHED            
22020 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
22030 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
22040 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
22050 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
22060 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41   SQLITE_LIMIT_VA
22070 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20  RIABLE_NUMBER   
22080 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e          9.#defin
22090 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  e SQLITE_LIMIT_T
220a0 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20  RIGGER_DEPTH    
220b0 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a          10../*.*
220c0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
220d0 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61  iling An SQL Sta
220e0 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52  tement.** KEYWOR
220f0 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65  DS: {SQL stateme
22100 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a  nt compiler}.**.
22110 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e  ** To execute an
22120 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d   SQL query, it m
22130 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d  ust first be com
22140 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74  piled into a byt
22150 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61  e-code.** progra
22160 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74  m using one of t
22170 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
22180 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
22190 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69  rgument, "db", i
221a0 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  s a [database co
221b0 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e  nnection] obtain
221c0 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69  ed from a.** pri
221d0 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  or successful ca
221e0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ll to [sqlite3_o
221f0 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
22200 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a  _open_v2()] or.*
22210 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  * [sqlite3_open1
22220 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62  6()].  The datab
22230 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
22240 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65  ust not have bee
22250 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  n closed..**.** 
22260 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
22270 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20  ent, "zSql", is 
22280 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  the statement to
22290 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e   be compiled, en
222a0 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68  coded.** as eith
222b0 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
222c0 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  16.  The sqlite3
222d0 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73  _prepare() and s
222e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
222f0 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  2().** interface
22300 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64  s use UTF-8, and
22310 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
22320 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  16() and sqlite3
22330 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a  _prepare16_v2().
22340 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a  ** use UTF-16..*
22350 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79  *.** ^If the nBy
22360 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c  te argument is l
22370 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74  ess than zero, t
22380 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64  hen zSql is read
22390 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69   up to the.** fi
223a0 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
223b0 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69  tor. ^If nByte i
223c0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
223d0 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d  then it is the m
223e0 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72  aximum.** number
223f0 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 64 20   of  bytes read 
22400 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65  from zSql.  ^Whe
22410 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e  n nByte is non-n
22420 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20  egative, the.** 
22430 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73  zSql string ends
22440 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20 66   at either the f
22450 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27  irst '\000' or '
22460 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74 65  \u0000' characte
22470 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74  r or.** the nByt
22480 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68  e-th byte, which
22490 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74  ever comes first
224a0 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20  . If the caller 
224b0 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68  knows.** that th
224c0 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e  e supplied strin
224d0 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  g is nul-termina
224e0 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20  ted, then there 
224f0 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65  is a small.** pe
22500 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74  rformance advant
22510 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64  age to be gained
22520 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e   by passing an n
22530 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74  Byte parameter t
22540 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20  hat.** is equal 
22550 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  to the number of
22560 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e   bytes in the in
22570 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e  put string <i>in
22580 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74  cluding</i>.** t
22590 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f  he nul-terminato
225a0 72 20 62 79 74 65 73 20 61 73 20 74 68 69 73 20  r bytes as this 
225b0 73 61 76 65 73 20 53 51 4c 69 74 65 20 66 72 6f  saves SQLite fro
225c0 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a 2a 20 6d  m having to.** m
225d0 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ake a copy of th
225e0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 0a  e input string..
225f0 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c  **.** ^If pzTail
22600 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
22610 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64  n *pzTail is mad
22620 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  e to point to th
22630 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20  e first byte.** 
22640 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20  past the end of 
22650 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74  the first SQL st
22660 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e  atement in zSql.
22670 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
22680 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65   only.** compile
22690 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65   the first state
226a0 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f  ment in zSql, so
226b0 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74   *pzTail is left
226c0 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20   pointing to.** 
226d0 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63  what remains unc
226e0 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ompiled..**.** ^
226f0 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20  *ppStmt is left 
22700 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f  pointing to a co
22710 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64  mpiled [prepared
22720 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
22730 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75   can be.** execu
22740 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
22750 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66  e3_step()].  ^If
22760 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72   there is an err
22770 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73  or, *ppStmt is s
22780 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20  et.** to NULL.  
22790 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65  ^If the input te
227a0 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53  xt contains no S
227b0 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74  QL (if the input
227c0 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20   is an empty.** 
227d0 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d  string or a comm
227e0 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d  ent) then *ppStm
227f0 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c  t is set to NULL
22800 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67  ..** The calling
22810 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65   procedure is re
22820 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65  sponsible for de
22830 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  leting the compi
22840 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  led.** SQL state
22850 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
22860 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
22870 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e  after it has fin
22880 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a  ished with it..*
22890 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74  * ppStmt may not
228a0 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
228b0 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65  ^On success, the
228c0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
228d0 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75  () family of rou
228e0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
228f0 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68  LITE_OK];.** oth
22900 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
22910 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
22920 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
22930 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
22940 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
22950 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e  repare16_v2() in
22960 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20  terfaces are.** 
22970 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
22980 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73  all new programs
22990 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20  . The two older 
229a0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72  interfaces are r
229b0 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62  etained.** for b
229c0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
229d0 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69  bility, but thei
229e0 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72  r use is discour
229f0 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65  aged..** ^In the
22a00 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73   "v2" interfaces
22a10 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  , the prepared s
22a20 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74  tatement.** that
22a30 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68   is returned (th
22a40 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
22a50 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e   object) contain
22a60 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
22a70 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  ** original SQL 
22a80 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65  text. This cause
22a90 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  s the [sqlite3_s
22aa0 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tep()] interface
22ab0 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69   to.** behave di
22ac0 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72  fferently in thr
22ad0 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ee ways:.**.** <
22ae0 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  ol>.** <li>.** ^
22af0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
22b00 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20  schema changes, 
22b10 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72  instead of retur
22b20 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48  ning [SQLITE_SCH
22b30 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c  EMA] as it.** al
22b40 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c  ways used to do,
22b50 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
22b60 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  ] will automatic
22b70 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74  ally recompile t
22b80 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  he SQL.** statem
22b90 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72  ent and try to r
22ba0 75 6e 20 69 74 20 61 67 61 69 6e 2e 0a 2a 2a 20  un it again..** 
22bb0 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
22bc0 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72  .** ^When an err
22bd0 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69  or occurs, [sqli
22be0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
22bf0 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74   return one of t
22c00 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b  he detailed.** [
22c10 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20  error codes] or 
22c20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
22c30 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65  codes].  ^The le
22c40 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61  gacy behavior wa
22c50 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74  s that.** [sqlit
22c60 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64  e3_step()] would
22c70 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67   only return a g
22c80 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45  eneric [SQLITE_E
22c90 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64  RROR] result cod
22ca0 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70  e.** and the app
22cb0 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68  lication would h
22cc0 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65  ave to make a se
22cd0 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cond call to [sq
22ce0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a  lite3_reset()].*
22cf0 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  * in order to fi
22d00 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
22d10 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  g cause of the p
22d20 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65  roblem. With the
22d30 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a   "v2" prepare.**
22d40 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
22d50 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73   underlying reas
22d60 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72  on for the error
22d70 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
22d80 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c  ediately..** </l
22d90 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
22da0 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69   ^If the specifi
22db0 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f  c value bound to
22dc0 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f   [parameter | ho
22dd0 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  st parameter] in
22de0 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63   the .** WHERE c
22df0 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c  lause might infl
22e00 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65  uence the choice
22e10 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66   of query plan f
22e20 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a  or a statement,.
22e30 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 74  ** then the stat
22e40 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75  ement will be au
22e50 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
22e60 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68  mpiled, as if th
22e70 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a  ere had been .**
22e80 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
22e90 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20  , on the first  
22ea0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
22eb0 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20   call following 
22ec0 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f  any change.** to
22ed0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
22ee0 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e  nd_text | bindin
22ef0 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72  gs] of that [par
22f00 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68  ameter]. .** ^Th
22f10 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65  e specific value
22f20 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65   of WHERE-clause
22f30 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67   [parameter] mig
22f40 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
22f50 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71   .** choice of q
22f60 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65  uery plan if the
22f70 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
22f80 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65  e left-hand side
22f90 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20   of a [LIKE].** 
22fa0 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  or [GLOB] operat
22fb0 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 72  or or if the par
22fc0 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72  ameter is compar
22fd0 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64  ed to an indexed
22fe0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74   column.** and t
22ff0 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  he [SQLITE_ENABL
23000 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65  E_STAT3] compile
23010 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
23020 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 68 65 20  enabled..** the 
23030 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f  .** </li>.** </o
23040 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l>.*/.int sqlite
23050 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c  3_prepare(.  sql
23060 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
23070 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
23080 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
23090 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
230a0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
230b0 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
230c0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
230d0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
230e0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
230f0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
23100 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
23110 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
23120 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
23130 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
23140 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
23150 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
23160 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
23170 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
23180 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
23190 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
231a0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
231b0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
231c0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
231d0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
231e0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
231f0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
23200 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
23210 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
23220 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
23230 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
23240 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
23250 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
23260 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
23270 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
23280 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
23290 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
232a0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
232b0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
232c0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
232d0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
232e0 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  re16(.  sqlite3 
232f0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
23300 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
23310 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
23320 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
23330 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
23340 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
23350 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
23360 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
23370 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
23380 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
23390 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
233a0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
233b0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
233c0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
233d0 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
233e0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
233f0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
23400 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
23410 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
23420 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20  _prepare16_v2(. 
23430 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
23440 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
23450 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
23460 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
23470 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
23480 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
23490 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
234a0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
234b0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
234c0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
234d0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
234e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
234f0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
23500 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
23510 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
23520 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
23530 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
23540 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
23550 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f  of zSql */.);../
23560 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
23570 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d  etrieving Statem
23580 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54  ent SQL.**.** ^T
23590 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
235a0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74  n be used to ret
235b0 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f  rieve a saved co
235c0 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e  py of the origin
235d0 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75  al.** SQL text u
235e0 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20  sed to create a 
235f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
23600 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61  ent] if that sta
23610 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f  tement was.** co
23620 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74  mpiled using eit
23630 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
23640 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
23650 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
23660 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  _v2()]..*/.const
23670 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
23680 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ql(sqlite3_stmt 
23690 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
236a0 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
236b0 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
236c0 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54  atement Writes T
236d0 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a  he Database.**.*
236e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
236f0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20  tmt_readonly(X) 
23700 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
23710 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
23720 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ) if.** and only
23730 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   if the [prepare
23740 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d  d statement] X m
23750 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63  akes no direct c
23760 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65  hanges to.** the
23770 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
23780 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a  database file..*
23790 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  *.** Note that [
237a0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
237b0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
237c0 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61  s] or.** [virtua
237d0 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20  l tables] might 
237e0 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
237f0 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61  ase indirectly a
23800 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e  s a side effect.
23810 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d    .** ^(For exam
23820 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69  ple, if an appli
23830 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61  cation defines a
23840 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28   function "eval(
23850 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c  )" that .** call
23860 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  s [sqlite3_exec(
23870 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c  )], then the fol
23880 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65  lowing SQL state
23890 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68  ment would.** ch
238a0 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
238b0 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73  e file through s
238c0 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a  ide-effects:.**.
238d0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
238e0 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43  pre>.**    SELEC
238f0 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46  T eval('DELETE F
23900 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32  ROM t1') FROM t2
23910 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
23920 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
23930 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b  ut because the [
23940 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
23950 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  t does not chang
23960 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
23970 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c  ile.** directly,
23980 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
23990 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73  adonly() would s
239a0 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65  till return true
239b0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73  .)^.**.** ^Trans
239c0 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73  action control s
239d0 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61  tatements such a
239e0 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d  s [BEGIN], [COMM
239f0 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c  IT], [ROLLBACK],
23a00 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c  .** [SAVEPOINT],
23a10 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63   and [RELEASE] c
23a20 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ause sqlite3_stm
23a30 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
23a40 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20  return true,.** 
23a50 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d  since the statem
23a60 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20  ents themselves 
23a70 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20  do not actually 
23a80 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
23a90 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65  ase but.** rathe
23aa0 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74  r they control t
23ab0 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65  he timing of whe
23ac0 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e  n other statemen
23ad0 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a  ts modify the .*
23ae0 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68  * database.  ^Th
23af0 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b  e [ATTACH] and [
23b00 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e  DETACH] statemen
23b10 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a  ts also cause.**
23b20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
23b30 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
23b40 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77  rn true since, w
23b50 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65  hile those state
23b60 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20  ments.** change 
23b70 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
23b80 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20  n of a database 
23b90 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79  connection, they
23ba0 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a   do not make .**
23bb0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
23bc0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64  content of the d
23bd0 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e  atabase files on
23be0 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71   disk..*/.int sq
23bf0 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
23c00 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  nly(sqlite3_stmt
23c10 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
23c20 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
23c30 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70 61 72  mine If A Prepar
23c40 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73  ed Statement Has
23c50 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a   Been Reset.**.*
23c60 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
23c70 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65  tmt_busy(S) inte
23c80 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
23c90 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
23ca0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
23cb0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68  d statement] S h
23cc0 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20  as been stepped 
23cd0 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73  at least once us
23ce0 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
23cf0 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61  _step(S)] but ha
23d00 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20 63 6f 6d  s not run to com
23d10 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f 72 20 68  pletion and/or h
23d20 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e 20  as not .** been 
23d30 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c  reset using [sql
23d40 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20  ite3_reset(S)]. 
23d50 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
23d60 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e  mt_busy(S).** in
23d70 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
23d80 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 61 20  false if S is a 
23d90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49  NULL pointer.  I
23da0 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a  f S is not a .**
23db0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e   NULL pointer an
23dc0 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74  d is not a point
23dd0 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70  er to a valid [p
23de0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23df0 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68  t].** object, th
23e00 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
23e10 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
23e20 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69   probably undesi
23e30 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  rable..**.** Thi
23e40 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
23e50 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69  be used in combi
23e60 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f  nation [sqlite3_
23e70 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20  next_stmt()].** 
23e80 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72  to locate all pr
23e90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
23ea0 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
23eb0 68 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a  h a database .**
23ec0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
23ed0 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20   are in need of 
23ee0 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68  being reset.  Th
23ef0 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a  is can be used,.
23f00 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** for example, 
23f10 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f  in diagnostic ro
23f20 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68  utines to search
23f30 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a   for prepared .*
23f40 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  * statements tha
23f50 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20  t are holding a 
23f60 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e  transaction open
23f70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
23f80 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74  _stmt_busy(sqlit
23f90 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
23fa0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61  * CAPI3REF: Dyna
23fb0 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61  mically Typed Va
23fc0 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  lue Object.** KE
23fd0 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74  YWORDS: {protect
23fe0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
23ff0 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  } {unprotected s
24000 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a  qlite3_value}.**
24010 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
24020 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  the sqlite3_valu
24030 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72  e object to repr
24040 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73  esent all values
24050 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
24060 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61  stored in a data
24070 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69  base table. SQLi
24080 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
24090 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68  typing.** for th
240a0 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72  e values it stor
240b0 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f  es.  ^Values sto
240c0 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76  red in sqlite3_v
240d0 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20  alue objects.** 
240e0 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c  can be integers,
240f0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
24100 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c  values, strings,
24110 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e   BLOBs, or NULL.
24120 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65  .**.** An sqlite
24130 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d  3_value object m
24140 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72  ay be either "pr
24150 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70  otected" or "unp
24160 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f  rotected"..** So
24170 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  me interfaces re
24180 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65  quire a protecte
24190 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
241a0 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63    Other interfac
241b0 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70  es.** will accep
241c0 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65  t either a prote
241d0 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f  cted or an unpro
241e0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
241f0 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69  alue..** Every i
24200 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63  nterface that ac
24210 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61  cepts sqlite3_va
24220 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70  lue arguments sp
24230 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68  ecifies.** wheth
24240 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71  er or not it req
24250 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65  uires a protecte
24260 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
24270 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73  .**.** The terms
24280 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64   "protected" and
24290 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72   "unprotected" r
242a0 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20  efer to whether 
242b0 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65  or not.** a mute
242c0 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69  x is held.  An i
242d0 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73  nternal mutex is
242e0 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74   held for a prot
242f0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
24300 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75  _value object bu
24310 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65  t no mutex is he
24320 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ld for an unprot
24330 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
24340 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20  _value object.  
24350 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
24360 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67  piled to be sing
24370 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28  le-threaded.** (
24380 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52  with [SQLITE_THR
24390 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77  EADSAFE=0] and w
243a0 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72  ith [sqlite3_thr
243b0 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72  eadsafe()] retur
243c0 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66  ning 0).** or if
243d0 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69   SQLite is run i
243e0 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64  n one of reduced
243f0 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a   mutex modes .**
24400 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
24410 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72  SINGLETHREAD] or
24420 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
24430 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20  MULTITHREAD].** 
24440 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f  then there is no
24450 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
24460 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
24470 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
24480 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
24490 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79  objects and they
244a0 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74   can be used int
244b0 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48  erchangeably.  H
244c0 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d  owever,.** for m
244d0 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74  aximum code port
244e0 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65  ability it is re
244f0 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
24500 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
24510 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69  till make the di
24520 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
24530 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
24540 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
24550 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
24560 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e  ects even when n
24570 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75  ot strictly requ
24580 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ired..**.** ^The
24590 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
245a0 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20  bjects that are 
245b0 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65  passed as parame
245c0 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ters into the.**
245d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
245e0 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  of [application-
245f0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
24600 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65  tions] are prote
24610 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  cted..** ^The sq
24620 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
24630 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
24640 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
24650 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e  n_value()] is un
24660 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e  protected..** Un
24670 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
24680 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
24690 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
246a0 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65   with.** [sqlite
246b0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
246c0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  ] and [sqlite3_b
246d0 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ind_value()]..**
246e0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
246f0 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  lue_blob | sqlit
24700 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d  e3_value_type()]
24710 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e   family of.** in
24720 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
24730 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
24740 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
24750 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
24760 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f  uct Mem sqlite3_
24770 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  value;../*.** CA
24780 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63  PI3REF: SQL Func
24790 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a  tion Context Obj
247a0 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ect.**.** The co
247b0 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
247c0 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
247d0 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
247e0 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
247f0 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
24800 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74  t.  ^A pointer t
24810 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e  o an sqlite3_con
24820 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69  text object.** i
24830 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70  s always first p
24840 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70  arameter to [app
24850 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
24860 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e   SQL functions].
24870 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
24880 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
24890 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
248a0 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73  ntation will pas
248b0 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65  s this.** pointe
248c0 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63  r through into c
248d0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
248e0 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71  _result_int | sq
248f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c  lite3_result()],
24900 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67  .** [sqlite3_agg
24910 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
24920 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ], [sqlite3_user
24930 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _data()],.** [sq
24940 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
24950 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c  _handle()], [sql
24960 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
24970 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  ()],.** and/or [
24980 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
24990 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  ata()]..*/.typed
249a0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
249b0 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65  3_context sqlite
249c0 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a  3_context;../*.*
249d0 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64  * CAPI3REF: Bind
249e0 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72  ing Values To Pr
249f0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
24a00 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
24a10 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20  host parameter} 
24a20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  {host parameters
24a30 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
24a40 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f  r name}.** KEYWO
24a50 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65  RDS: {SQL parame
24a60 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65  ter} {SQL parame
24a70 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72  ters} {parameter
24a80 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20   binding}.**.** 
24a90 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61  ^(In the SQL sta
24aa0 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75  tement text inpu
24ab0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
24ac0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
24ad0 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a  its variants,.**
24ae0 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65   literals may be
24af0 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b   replaced by a [
24b00 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20  parameter] that 
24b10 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66  matches one of f
24b20 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70  ollowing.** temp
24b30 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  lates:.**.** <ul
24b40 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20  >.** <li>  ?.** 
24b50 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c  <li>  ?NNN.** <l
24b60 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  :VVV.** <li>
24b70 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    @VVV.** <li>  
24b80 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  $VVV.** </ul>.**
24b90 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c  .** In the templ
24ba0 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20  ates above, NNN 
24bb0 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e  represents an in
24bc0 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a  teger literal,.*
24bd0 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73  * and VVV repres
24be0 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d  ents an alphanum
24bf0 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e  eric identifier.
24c00 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  )^  ^The values 
24c10 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61  of these.** para
24c20 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c  meters (also cal
24c30 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65  led "host parame
24c40 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53  ter names" or "S
24c50 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a  QL parameters").
24c60 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73  ** can be set us
24c70 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
24c80 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
24c90 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a  s defined here..
24ca0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
24cb0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
24cc0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
24cd0 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c  ) routines is al
24ce0 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  ways.** a pointe
24cf0 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
24d00 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72  3_stmt] object r
24d10 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  eturned from.** 
24d20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
24d30 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61  _v2()] or its va
24d40 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  riants..**.** ^T
24d50 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
24d60 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
24d70 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d  of the SQL param
24d80 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a  eter to be set..
24d90 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  ** ^The leftmost
24da0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68   SQL parameter h
24db0 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
24dc0 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d  .  ^When the sam
24dd0 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70  e named.** SQL p
24de0 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64  arameter is used
24df0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
24e00 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
24e10 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72  equent.** occurr
24e20 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73  ences have the s
24e30 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65  ame index as the
24e40 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
24e50 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78  e..** ^The index
24e60 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d   for named param
24e70 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f  eters can be loo
24e80 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65  ked up using the
24e90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
24ea0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
24eb0 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69  x()] API if desi
24ec0 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78  red.  ^The index
24ed0 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70  .** for "?NNN" p
24ee0 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65  arameters is the
24ef0 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a   value of NNN..*
24f00 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65  * ^The NNN value
24f10 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e   must be between
24f20 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69   1 and the [sqli
24f30 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
24f40 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54  parameter [SQLIT
24f50 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
24f60 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c  _NUMBER] (defaul
24f70 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a  t value: 999)..*
24f80 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
24f90 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
24fa0 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f  value to bind to
24fb0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
24fc0 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65  **.** ^(In those
24fd0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68   routines that h
24fe0 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67  ave a fourth arg
24ff0 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65  ument, its value
25000 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
25010 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
25020 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f  e parameter.  To
25030 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76   be clear: the v
25040 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
25050 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65  umber of <u>byte
25060 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c  s</u> in the val
25070 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ue, not the numb
25080 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
25090 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .)^.** ^If the f
250a0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
250b0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
250c0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
250d0 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20  tring is.** the 
250e0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
250f0 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
25100 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
25110 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67  .** If a non-neg
25120 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61 72  ative fourth par
25130 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69 64  ameter is provid
25140 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  ed to sqlite3_bi
25150 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20  nd_text().** or 
25160 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
25170 74 31 36 28 29 20 74 68 65 6e 20 74 68 61 74 20  t16() then that 
25180 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
25190 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65  e the byte offse
251a0 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e  t.** where the N
251b0 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f  UL terminator wo
251c0 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69  uld occur assumi
251d0 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77 65  ng the string we
251e0 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e  re NUL.** termin
251f0 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55  ated.  If any NU
25200 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63  L characters occ
25210 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73 65  ur at byte offse
25220 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a  ts less than .**
25230 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
25240 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
25250 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  er then the resu
25260 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c  lting string val
25270 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61  ue will.** conta
25280 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  in embedded NULs
25290 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66  .  The result of
252a0 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76   expressions inv
252b0 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a  olving strings.*
252c0 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20  * with embedded 
252d0 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65  NULs is undefine
252e0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  d..**.** ^The fi
252f0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  fth argument to 
25300 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
25310 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e  b(), sqlite3_bin
25320 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a  d_text(), and.**
25330 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
25340 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74  xt16() is a dest
25350 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64  ructor used to d
25360 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
25370 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20  OB or.** string 
25380 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
25390 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
253a0 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63  t.  ^The destruc
253b0 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a  tor is called.**
253c0 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
253d0 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  he BLOB or strin
253e0 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61  g even if the ca
253f0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  ll to sqlite3_bi
25400 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71  nd_blob(),.** sq
25410 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
25420 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ), or sqlite3_bi
25430 6e 64 5f 74 65 78 74 31 36 28 29 20 66 61 69 6c  nd_text16() fail
25440 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20  s.  .** ^If the 
25450 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69  fifth argument i
25460 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c  s.** the special
25470 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53   value [SQLITE_S
25480 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c  TATIC], then SQL
25490 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
254a0 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74   the.** informat
254b0 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63  ion is in static
254c0 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63  , unmanaged spac
254d0 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e  e and does not n
254e0 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e  eed to be freed.
254f0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
25500 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74  h argument has t
25510 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  he value [SQLITE
25520 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65  _TRANSIENT], the
25530 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  n.** SQLite make
25540 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  s its own privat
25550 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61  e copy of the da
25560 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ta immediately, 
25570 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71  before.** the sq
25580 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
25590 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a  outine returns..
255a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
255b0 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
255c0 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73  () routine binds
255d0 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74   a BLOB of lengt
255e0 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66  h N that.** is f
255f0 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65  illed with zeroe
25600 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20  s.  ^A zeroblob 
25610 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f  uses a fixed amo
25620 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  unt of memory.**
25630 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65   (just an intege
25640 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69  r to hold its si
25650 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20  ze) while it is 
25660 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e  being processed.
25670 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72  .** Zeroblobs ar
25680 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65  e intended to se
25690 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64  rve as placehold
256a0 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68  ers for BLOBs wh
256b0 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69  ose.** content i
256c0 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20  s later written 
256d0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
256e0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
256f0 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
25700 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  /O] routines..**
25710 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c   ^A negative val
25720 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
25730 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
25740 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
25750 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79  B..**.** ^If any
25760 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
25770 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
25780 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74  s are called wit
25790 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
257a0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65  .** for the [pre
257b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
257c0 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61   or with a prepa
257d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f  red statement fo
257e0 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69  r which.** [sqli
257f0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
25800 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65  been called more
25810 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b   recently than [
25820 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
25830 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61  ,.** then the ca
25840 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ll will return [
25850 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
25860 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f   If any sqlite3_
25870 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69  bind_().** routi
25880 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b  ne is passed a [
25890 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
258a0 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65  nt] that has bee
258b0 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65  n finalized, the
258c0 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e  .** result is un
258d0 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
258e0 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ably harmful..**
258f0 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72  .** ^Bindings ar
25900 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79  e not cleared by
25910 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
25920 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a  set()] routine..
25930 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61  ** ^Unbound para
25940 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72  meters are inter
25950 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a  preted as NULL..
25960 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
25970 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e  e3_bind_* routin
25980 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
25990 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
259a0 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72   or an.** [error
259b0 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69   code] if anythi
259c0 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a  ng goes wrong..*
259d0 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  * ^[SQLITE_RANGE
259e0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
259f0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   the parameter.*
25a00 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  * index is out o
25a10 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49  f range.  ^[SQLI
25a20 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74  TE_NOMEM] is ret
25a30 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28  urned if malloc(
25a40 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53  ) fails..**.** S
25a50 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
25a60 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
25a70 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73  _count()],.** [s
25a80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
25a90 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
25aa0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
25ab0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
25ac0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
25ad0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71  te3_bind_blob(sq
25ae0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
25af0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
25b00 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
25b10 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
25b20 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73  e3_bind_double(s
25b30 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
25b40 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20  t, double);.int 
25b50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
25b60 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
25b70 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  int, int);.int s
25b80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36  qlite3_bind_int6
25b90 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
25ba0 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e   int, sqlite3_in
25bb0 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  t64);.int sqlite
25bc0 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69  3_bind_null(sqli
25bd0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
25be0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
25bf0 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  d_text(sqlite3_s
25c00 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
25c10 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76   char*, int n, v
25c20 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
25c30 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
25c40 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
25c50 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
25c60 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
25c70 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
25c80 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
25c90 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
25ca0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
25cb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
25cc0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
25cd0 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  d_zeroblob(sqlit
25ce0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
25cf0 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
25d00 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
25d10 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
25d20 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
25d30 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64  tine can be used
25d40 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
25d50 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61  ber of [SQL para
25d60 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20  meters].** in a 
25d70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
25d80 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d  ent].  SQL param
25d90 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73  eters are tokens
25da0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20   of the.** form 
25db0 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41  "?", "?NNN", ":A
25dc0 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20  AA", "$AAA", or 
25dd0 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76  "@AAA" that serv
25de0 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c  e as.** placehol
25df0 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20  ders for values 
25e00 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65  that are [sqlite
25e10 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f  3_bind_blob | bo
25e20 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70  und].** to the p
25e30 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c  arameters at a l
25e40 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  ater time..**.**
25e50 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
25e60 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
25e70 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
25e80 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74  e largest (right
25e90 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74  most).** paramet
25ea0 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  er. For all form
25eb0 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
25ec0 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
25ed0 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75  ond to the.** nu
25ee0 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70  mber of unique p
25ef0 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
25f00 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
25f10 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75   ?NNN form are u
25f20 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
25f30 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
25f40 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53   list.)^.**.** S
25f50 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
25f60 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
25f70 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
25f80 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
25f90 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
25fa0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
25fb0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
25fc0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
25fd0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
25fe0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71  rameter_count(sq
25ff0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
26000 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
26010 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61  ame Of A Host Pa
26020 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54  rameter.**.** ^T
26030 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
26040 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50  parameter_name(P
26050 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
26060 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  turns.** the nam
26070 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53  e of the N-th [S
26080 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
26090 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
260a0 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
260b0 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  ^(SQL parameters
260c0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
260d0 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
260e0 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
260f0 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
26100 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
26110 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
26120 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
26130 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
26140 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
26150 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
26160 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
26170 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
26180 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
26190 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
261a0 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72   name.)^.** ^Par
261b0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
261c0 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
261d0 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
261e0 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
261f0 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65  .** and are refe
26200 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65  rred to as "name
26210 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d  less" or "anonym
26220 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
26230 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
26240 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  t host parameter
26250 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
26260 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a   1, not 0..**.**
26270 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e   ^If the value N
26280 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
26290 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20   or if the N-th 
262a0 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
262b0 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
262c0 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
262d0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
262e0 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77  string is.** alw
262f0 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63  ays in UTF-8 enc
26300 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
26310 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
26320 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
26330 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
26340 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
26350 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
26360 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
26370 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
26380 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
26390 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
263a0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
263b0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
263c0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
263d0 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
263e0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
263f0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
26400 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  ]..*/.const char
26410 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   *sqlite3_bind_p
26420 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71  arameter_name(sq
26430 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
26440 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
26450 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50  EF: Index Of A P
26460 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20  arameter With A 
26470 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a  Given Name.**.**
26480 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64   ^Return the ind
26490 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72  ex of an SQL par
264a0 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73  ameter given its
264b0 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20   name.  ^The.** 
264c0 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75  index value retu
264d0 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65  rned is suitable
264e0 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20   for use as the 
264f0 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65  second.** parame
26500 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
26510 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
26520 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a  3_bind()].  ^A z
26530 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ero.** is return
26540 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e  ed if no matchin
26550 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66  g parameter is f
26560 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61  ound.  ^The para
26570 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75  meter.** name mu
26580 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55  st be given in U
26590 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65  TF-8 even if the
265a0 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
265b0 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61  ent.** was prepa
265c0 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20  red from UTF-16 
265d0 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  text using [sqli
265e0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
265f0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
26600 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
26610 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
26620 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
26630 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
26640 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
26650 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
26660 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
26670 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ex()]..*/.int sq
26680 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
26690 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74  eter_index(sqlit
266a0 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20  e3_stmt*, const 
266b0 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f  char *zName);../
266c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
266d0 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67  eset All Binding
266e0 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20  s On A Prepared 
266f0 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
26700 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65  ^Contrary to the
26710 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61   intuition of ma
26720 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ny, [sqlite3_res
26730 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72  et()] does not r
26740 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  eset.** the [sql
26750 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
26760 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20   bindings] on a 
26770 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26780 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68  ent]..** ^Use th
26790 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65  is routine to re
267a0 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72  set all host par
267b0 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e  ameters to NULL.
267c0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
267d0 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73  clear_bindings(s
267e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
267f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
26800 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e  Number Of Column
26810 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
26820 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  t.**.** ^Return 
26830 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
26840 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
26850 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64  ult set returned
26860 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   by the.** [prep
26870 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
26880 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
26890 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d  eturns 0 if pStm
268a0 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73  t is an SQL.** s
268b0 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f  tatement that do
268c0 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61  es not return da
268d0 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ta (for example 
268e0 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a  an [UPDATE])..**
268f0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
26900 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
26910 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  t()].*/.int sqli
26920 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
26930 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
26940 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
26950 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e  PI3REF: Column N
26960 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74  ames In A Result
26970 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73   Set.**.** ^Thes
26980 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
26990 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67  n the name assig
269a0 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75  ned to a particu
269b0 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e  lar column.** in
269c0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
269d0 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  of a [SELECT] st
269e0 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73  atement.  ^The s
269f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
26a00 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  me().** interfac
26a10 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
26a20 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
26a30 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
26a40 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c  tring.** and sql
26a50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
26a60 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  16() returns a p
26a70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
26a80 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
26a90 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
26aa0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
26ab0 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70  ter is the [prep
26ac0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
26ad0 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ** that implemen
26ae0 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  ts the [SELECT] 
26af0 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20  statement. ^The 
26b00 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
26b10 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   is the.** colum
26b20 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20  n number.  ^The 
26b30 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
26b40 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a  is number 0..**.
26b50 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
26b60 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
26b70 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65  is valid until e
26b80 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61  ither the [prepa
26b90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
26ba0 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62  * is destroyed b
26bb0 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  y [sqlite3_final
26bc0 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
26bd0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
26be0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
26bf0 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20  * reprepared by 
26c00 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74  the first call t
26c10 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
26c20 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  )] for a particu
26c30 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e  lar run.** or un
26c40 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c  til the next cal
26c50 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
26c60 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72  column_name() or
26c70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
26c80 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20  name16() on the 
26c90 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a  same column..**.
26ca0 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
26cb0 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75  alloc() fails du
26cc0 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73  ring the process
26cd0 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f  ing of either ro
26ce0 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78  utine.** (for ex
26cf0 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63  ample during a c
26d00 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55  onversion from U
26d10 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20  TF-8 to UTF-16) 
26d20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  then a.** NULL p
26d30 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
26d40 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  ed..**.** ^The n
26d50 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20  ame of a result 
26d60 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61  column is the va
26d70 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20  lue of the "AS" 
26d80 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  clause for.** th
26d90 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68  at column, if th
26da0 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61  ere is an AS cla
26db0 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69  use.  If there i
26dc0 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a  s no AS clause.*
26dd0 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20  * then the name 
26de0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73  of the column is
26df0 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64   unspecified and
26e00 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d   may change from
26e10 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  .** one release 
26e20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  of SQLite to the
26e30 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20   next..*/.const 
26e40 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
26e50 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  lumn_name(sqlite
26e60 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
26e70 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
26e80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
26e90 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
26ea0 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int N);../*.**
26eb0 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63   CAPI3REF: Sourc
26ec0 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51  e Of Data In A Q
26ed0 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a  uery Result.**.*
26ee0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
26ef0 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e  s provide a mean
26f00 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74  s to determine t
26f10 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  he database, tab
26f20 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65  le, and.** table
26f30 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20   column that is 
26f40 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20  the origin of a 
26f50 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c  particular resul
26f60 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b  t column in.** [
26f70 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
26f80 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  t..** ^The name 
26f90 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
26fa0 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75  or table or colu
26fb0 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e  mn can be return
26fc0 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20  ed as.** either 
26fd0 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  a UTF-8 or UTF-1
26fe0 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
26ff0 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69  _database_ routi
27000 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68  nes return.** th
27010 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c  e database name,
27020 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75   the _table_ rou
27030 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
27040 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64   table name, and
27050 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20  .** the origin_ 
27060 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
27070 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e  the column name.
27080 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
27090 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69  d string is vali
270a0 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65  d until the [pre
270b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
270c0 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a   is destroyed.**
270d0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
270e0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
270f0 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
27100 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
27110 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
27120 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
27130 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
27140 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
27150 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
27160 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d  or until the sam
27170 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  e information is
27180 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67   requested.** ag
27190 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65  ain in a differe
271a0 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a  nt encoding..**.
271b0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65  ** ^The names re
271c0 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f  turned are the o
271d0 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73  riginal un-alias
271e0 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a  ed names of the.
271f0 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ** database, tab
27200 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a  le, and column..
27210 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
27220 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
27230 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73  se interfaces is
27240 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
27250 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65  tement]..** ^The
27260 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
27270 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
27280 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65  about the Nth re
27290 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75  sult column retu
272a0 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73  rned by.** the s
272b0 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20  tatement, where 
272c0 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
272d0 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
272e0 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d  t..** ^The left-
272f0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63  most column is c
27300 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73  olumn 0 for thes
27310 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
27320 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f  * ^If the Nth co
27330 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
27340 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
27350 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20  s an expression 
27360 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61  or.** subquery a
27370 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75  nd is not a colu
27380 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61  mn value, then a
27390 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  ll of these func
273a0 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tions return.** 
273b0 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f  NULL.  ^These ro
273c0 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f  utine might also
273d0 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20   return NULL if 
273e0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
273f0 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63  ion error.** occ
27400 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65  urs.  ^Otherwise
27410 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68  , they return th
27420 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74  e name of the at
27430 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c  tached database,
27440 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f   table,.** or co
27450 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20  lumn that query 
27460 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61  result column wa
27470 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  s extracted from
27480 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68  ..**.** ^As with
27490 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74   all other SQLit
274a0 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68  e APIs, those wh
274b0 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69  ose names end wi
274c0 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a  th "16" return.*
274d0 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  * UTF-16 encoded
274e0 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65   strings and the
274f0 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73   other functions
27500 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a   return UTF-8..*
27510 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73  *.** ^These APIs
27520 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61   are only availa
27530 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
27540 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
27550 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
27560 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
27570 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72  N_METADATA] C-pr
27580 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f  eprocessor symbo
27590 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  l..**.** If two 
275a0 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
275b0 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
275c0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
275d0 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73  es against the s
275e0 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  ame.** prepared 
275f0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f  statement and co
27600 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65  lumn at the same
27610 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
27620 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e  esults are.** un
27630 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  defined..**.** I
27640 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
27650 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
27660 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  r more.** [sqlit
27670 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
27680 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e  se_name | column
27690 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66   metadata interf
276a0 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65  aces].** for the
276b0 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
276c0 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72  statement] and r
276d0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  esult column.** 
276e0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
276f0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
27700 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
27710 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
27720 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
27730 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c  atabase_name(sql
27740 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
27750 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
27760 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
27770 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  base_name16(sqli
27780 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
27790 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
277a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
277b0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
277c0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
277d0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
277e0 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31  lumn_table_name1
277f0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
27800 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
27810 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
27820 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c  _origin_name(sql
27830 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
27840 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
27850 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
27860 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  in_name16(sqlite
27870 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
27880 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
27890 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65  eclared Datatype
278a0 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75   Of A Query Resu
278b0 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  lt.**.** ^(The f
278c0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
278d0 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
278e0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20  atement]..** If 
278f0 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69  this statement i
27900 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  s a [SELECT] sta
27910 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e  tement and the N
27920 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
27930 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73  .** returned res
27940 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20  ult set of that 
27950 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61  [SELECT] is a ta
27960 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20  ble column (not 
27970 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
27980 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68   or subquery) th
27990 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  en the declared 
279a0 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c  type of the tabl
279b0 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72  e.** column is r
279c0 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20  eturned.)^  ^If 
279d0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
279e0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
279f0 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
27a00 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
27a10 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
27a20 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
27a30 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  d..** ^The retur
27a40 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c  ned string is al
27a50 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64  ways UTF-8 encod
27a60 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20  ed..**.** ^(For 
27a70 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74  example, given t
27a80 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
27a90 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45  ma:.**.** CREATE
27aa0 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52   TABLE t1(c1 VAR
27ab0 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64  IANT);.**.** and
27ac0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73   the following s
27ad0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
27ae0 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53  ompiled:.**.** S
27af0 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31  ELECT c1 + 1, c1
27b00 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20   FROM t1;.**.** 
27b10 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75  this routine wou
27b20 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74  ld return the st
27b30 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66  ring "VARIANT" f
27b40 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65  or the second re
27b50 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28  sult.** column (
27b60 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c  i==1), and a NUL
27b70 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68  L pointer for th
27b80 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63  e first result c
27b90 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a  olumn (i==0).)^.
27ba0 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
27bb0 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74  es dynamic run-t
27bc0 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f  ime typing.  ^So
27bd0 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20   just because a 
27be0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63  column.** is dec
27bf0 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e  lared to contain
27c00 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79   a particular ty
27c10 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e  pe does not mean
27c20 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74   that the.** dat
27c30 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74  a stored in that
27c40 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68   column is of th
27c50 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e  e declared type.
27c60 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73    SQLite is.** s
27c70 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62  trongly typed, b
27c80 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73  ut the typing is
27c90 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61   dynamic not sta
27ca0 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69  tic.  ^Type.** i
27cb0 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
27cc0 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c  h individual val
27cd0 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68  ues, not with th
27ce0 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20  e containers.** 
27cf0 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f  used to hold tho
27d00 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f  se values..*/.co
27d10 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
27d20 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
27d30 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
27d40 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
27d50 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
27d60 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69  _decltype16(sqli
27d70 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
27d80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27d90 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c   Evaluate An SQL
27da0 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
27db0 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72   After a [prepar
27dc0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61  ed statement] ha
27dd0 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20  s been prepared 
27de0 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20  using either.** 
27df0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
27e00 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
27e10 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
27e20 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  )] or one of the
27e30 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
27e40 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70  faces [sqlite3_p
27e50 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71  repare()] or [sq
27e60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
27e70 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  )], this functio
27e80 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c  n.** must be cal
27e90 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  led one or more 
27ea0 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74  times to evaluat
27eb0 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e  e the statement.
27ec0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69  .**.** The detai
27ed0 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69  ls of the behavi
27ee0 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  or of the sqlite
27ef0 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61  3_step() interfa
27f00 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ce depend.** on 
27f10 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74  whether the stat
27f20 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72  ement was prepar
27f30 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77  ed using the new
27f40 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  er "v2" interfac
27f50 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
27f60 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
27f70 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
27f80 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20  16_v2()] or the 
27f90 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20  older legacy.** 
27fa0 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74  interface [sqlit
27fb0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
27fc0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
27fd0 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73  re16()].  The us
27fe0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20  e of the.** new 
27ff0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
28000 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
28010 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  r new applicatio
28020 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63  ns but the legac
28030 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77  y.** interface w
28040 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ill continue to 
28050 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a  be supported..**
28060 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61  .** ^In the lega
28070 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
28080 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77  e return value w
28090 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53  ill be either [S
280a0 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20  QLITE_BUSY],.** 
280b0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b  [SQLITE_DONE], [
280c0 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51  SQLITE_ROW], [SQ
280d0 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20  LITE_ERROR], or 
280e0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
280f0 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76  .** ^With the "v
28100 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e  2" interface, an
28110 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b  y of the other [
28120 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72  result codes] or
28130 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
28140 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68  sult codes] migh
28150 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  t be returned as
28160 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   well..**.** ^[S
28170 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e  QLITE_BUSY] mean
28180 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
28190 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75  ase engine was u
281a0 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65  nable to acquire
281b0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
281c0 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20   locks it needs 
281d0 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20  to do its job.  
281e0 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ^If the statemen
281f0 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a  t is a [COMMIT].
28200 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74  ** or occurs out
28210 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69  side of an expli
28220 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
28230 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65   then you can re
28240 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  try the.** state
28250 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74  ment.  If the st
28260 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61  atement is not a
28270 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63   [COMMIT] and oc
28280 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a  curs within an.*
28290 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  * explicit trans
282a0 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20  action then you 
282b0 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20  should rollback 
282c0 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
282d0 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e  before.** contin
282e0 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  uing..**.** ^[SQ
282f0 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73  LITE_DONE] means
28300 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d   that the statem
28310 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64  ent has finished
28320 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75   executing.** su
28330 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c  ccessfully.  sql
28340 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
28350 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
28360 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76   again on this v
28370 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
28380 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20  e without first 
28390 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
283a0 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73  _reset()] to res
283b0 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a  et the virtual.*
283c0 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74  * machine back t
283d0 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
283e0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ate..**.** ^If t
283f0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
28400 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20   being executed 
28410 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61  returns any data
28420 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52  , then [SQLITE_R
28430 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  OW].** is return
28440 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e  ed each time a n
28450 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69  ew row of data i
28460 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63  s ready for proc
28470 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a  essing by the.**
28480 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c   caller. The val
28490 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73  ues may be acces
284a0 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63  sed using the [c
284b0 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
284c0 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69  ctions]..** sqli
284d0 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61  te3_step() is ca
284e0 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65  lled again to re
284f0 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20  trieve the next 
28500 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  row of data..**.
28510 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ** ^[SQLITE_ERRO
28520 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  R] means that a 
28530 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28  run-time error (
28540 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72  such as a constr
28550 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f  aint.** violatio
28560 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e  n) has occurred.
28570 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
28580 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
28590 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a  alled again on.*
285a0 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69  * the VM. More i
285b0 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62  nformation may b
285c0 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69  e found by calli
285d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ng [sqlite3_errm
285e0 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  sg()]..** ^With 
285f0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
28600 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65  face, a more spe
28610 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
28620 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (for example,.*
28630 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  * [SQLITE_INTERR
28640 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43  UPT], [SQLITE_SC
28650 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  HEMA], [SQLITE_C
28660 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20  ORRUPT], and so 
28670 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65  forth).** can be
28680 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c   obtained by cal
28690 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
286a0 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a  set()] on the.**
286b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
286c0 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20  ment].  ^In the 
286d0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a  "v2" interface,.
286e0 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  ** the more spec
286f0 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
28700 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  is returned dire
28710 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ctly by sqlite3_
28720 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53  step()..**.** [S
28730 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65  QLITE_MISUSE] me
28740 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69  ans that the thi
28750 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61  s routine was ca
28760 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61  lled inappropria
28770 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73  tely..** Perhaps
28780 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f   it was called o
28790 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
287a0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
287b0 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65  s.** already bee
287c0 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  n [sqlite3_final
287d0 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d  ize | finalized]
287e0 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20   or on one that 
287f0 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  had.** previousl
28800 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  y returned [SQLI
28810 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51  TE_ERROR] or [SQ
28820 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20  LITE_DONE].  Or 
28830 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74  it could.** be t
28840 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
28850 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
28860 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69  onnection is bei
28870 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f  ng used by two o
28880 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64  r.** more thread
28890 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f  s at the same mo
288a0 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a  ment in time..**
288b0 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73  .** For all vers
288c0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75  ions of SQLite u
288d0 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69  p to and includi
288e0 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63  ng 3.6.23.1, a c
288f0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
28900 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20  e3_reset()] was 
28910 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20 73  required after s
28920 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65  qlite3_step() re
28930 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a  turned anything.
28940 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ** other than [S
28950 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72  QLITE_ROW] befor
28960 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74  e any subsequent
28970 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a   invocation of.*
28980 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
28990 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65  .  Failure to re
289a0 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
289b0 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
289c0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65   .** [sqlite3_re
289d0 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73  set()] would res
289e0 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54  ult in an [SQLIT
289f0 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e  E_MISUSE] return
28a00 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33   from.** sqlite3
28a10 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66  _step().  But af
28a20 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e  ter version 3.6.
28a30 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74  23.1, sqlite3_st
28a40 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61  ep() began.** ca
28a50 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
28a60 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69  eset()] automati
28a70 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69  cally in this ci
28a80 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65  rcumstance rathe
28a90 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e  r.** than return
28aa0 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  ing [SQLITE_MISU
28ab0 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f  SE].  This is no
28ac0 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63  t considered a c
28ad0 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20  ompatibility.** 
28ae0 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e  break because an
28af0 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68  y application th
28b00 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73  at ever receives
28b10 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53   an SQLITE_MISUS
28b20 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72  E error.** is br
28b30 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69  oken by definiti
28b40 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  on.  The [SQLITE
28b50 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d  _OMIT_AUTORESET]
28b60 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
28b70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75  tion.** can be u
28b80 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74  sed to restore t
28b90 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
28ba0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f  or..**.** <b>Goo
28bb0 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65  fy Interface Ale
28bc0 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c  rt:</b> In the l
28bd0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
28be0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
28bf0 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79  p().** API alway
28c00 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65  s returns a gene
28c10 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20  ric error code, 
28c20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
28c30 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a  following any.**
28c40 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
28c50 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
28c60 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  and [SQLITE_MISU
28c70 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63  SE].  You must c
28c80 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  all.** [sqlite3_
28c90 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
28ca0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
28cb0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
28cc0 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  d one of the.** 
28cd0 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
28ce0 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74  codes] that bett
28cf0 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65  er describes the
28d00 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64   error..** We ad
28d10 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73  mit that this is
28d20 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e   a goofy design.
28d30 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61    The problem ha
28d40 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20  s been fixed.** 
28d50 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  with the "v2" in
28d60 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75  terface.  If you
28d70 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20   prepare all of 
28d80 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65  your SQL stateme
28d90 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74  nts.** using eit
28da0 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
28db0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
28dc0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
28dd0 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a  _v2()] instead.*
28de0 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20  * of the legacy 
28df0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
28e00 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
28e10 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e  _prepare16()] in
28e20 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65  terfaces,.** the
28e30 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  n the more speci
28e40 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
28e50 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64  ] are returned d
28e60 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71  irectly.** by sq
28e70 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54  lite3_step().  T
28e80 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76  he use of the "v
28e90 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
28ea0 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a  recommended..*/.
28eb0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70  int sqlite3_step
28ec0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
28ed0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28ee0 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  : Number of colu
28ef0 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20  mns in a result 
28f00 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  set.**.** ^The s
28f10 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
28f20 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  t(P) interface r
28f30 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
28f40 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
28f50 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72  the.** current r
28f60 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
28f70 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65   set of [prepare
28f80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
28f90 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20  ** ^If prepared 
28fa0 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73  statement P does
28fb0 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74   not have result
28fc0 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72  s ready to retur
28fd0 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20  n.** (via calls 
28fe0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
28ff0 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c  column_int | sql
29000 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d  ite3_column_*()]
29010 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
29020 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  s) then sqlite3_
29030 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65  data_count(P) re
29040 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65  turns 0..** ^The
29050 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
29060 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61  unt(P) routine a
29070 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66  lso returns 0 if
29080 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   P is a NULL poi
29090 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  nter..** ^The sq
290a0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
290b0 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  (P) routine retu
290c0 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65  rns 0 if the pre
290d0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a  vious call to.**
290e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28   [sqlite3_step](
290f0 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  P) returned [SQL
29100 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65  ITE_DONE].  ^The
29110 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
29120 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72  unt(P).** will r
29130 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69  eturn non-zero i
29140 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  f previous call 
29150 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
29160 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ](P) returned.**
29170 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65   [SQLITE_ROW], e
29180 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73  xcept in the cas
29190 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41  e of the [PRAGMA
291a0 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63   incremental_vac
291b0 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74  uum].** where it
291c0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
291d0 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20  zero since each 
291e0 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c  step of that mul
291f0 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d  ti-step.** pragm
29200 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75  a returns 0 colu
29210 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  mns of data..**.
29220 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
29230 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
29240 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nt()].*/.int sql
29250 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
29260 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
29270 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
29280 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74  I3REF: Fundament
29290 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20  al Datatypes.** 
292a0 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
292b0 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76  _TEXT.**.** ^(Ev
292c0 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c  ery value in SQL
292d0 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66  ite has one of f
292e0 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20  ive fundamental 
292f0 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a  datatypes:.**.**
29300 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34   <ul>.** <li> 64
29310 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
29320 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ger.** <li> 64-b
29330 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67  it IEEE floating
29340 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a   point number.**
29350 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20   <li> string.** 
29360 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69  <li> BLOB.** <li
29370 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29  > NULL.** </ul>)
29380 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  ^.**.** These co
29390 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65  nstants are code
293a0 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68  s for each of th
293b0 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a  ose types..**.**
293c0 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53   Note that the S
293d0 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74  QLITE_TEXT const
293e0 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65  ant was also use
293f0 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73  d in SQLite vers
29400 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63  ion 2.** for a c
29410 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72  ompletely differ
29420 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f  ent meaning.  So
29430 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b  ftware that link
29440 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a  s against both.*
29450 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
29460 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65   2 and SQLite ve
29470 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75  rsion 3 should u
29480 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c  se SQLITE3_TEXT,
29490 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   not.** SQLITE_T
294a0 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  EXT..*/.#define 
294b0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20  SQLITE_INTEGER  
294c0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
294d0 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66  _FLOAT    2.#def
294e0 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20  ine SQLITE_BLOB 
294f0 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
29500 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a  LITE_NULL     5.
29510 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45  #ifdef SQLITE_TE
29520 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  XT.# undef SQLIT
29530 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64  E_TEXT.#else.# d
29540 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58  efine SQLITE_TEX
29550 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23  T     3.#endif.#
29560 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54  define SQLITE3_T
29570 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a  EXT     3../*.**
29580 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
29590 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20  t Values From A 
295a0 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44  Query.** KEYWORD
295b0 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  S: {column acces
295c0 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  s functions}.**.
295d0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
295e0 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75  s form the "resu
295f0 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66 61 63  lt set" interfac
29600 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  e..**.** ^These 
29610 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
29620 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
29630 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d  t a single colum
29640 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
29650 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f  .** result row o
29660 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20  f a query.  ^In 
29670 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66  every case the f
29680 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
29690 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
296a0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
296b0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
296c0 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65  s being evaluate
296d0 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
296e0 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77  stmt*].** that w
296f0 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  as returned from
29700 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29710 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  e_v2()] or one o
29720 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a  f its variants).
29730 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ** and the secon
29740 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
29750 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
29760 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20  olumn for which 
29770 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73  information.** s
29780 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
29790 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  d. ^The leftmost
297a0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
297b0 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68  esult set has th
297c0 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54  e index 0..** ^T
297d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
297e0 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
297f0 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  lt can be determ
29800 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
29810 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
29820 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  unt()]..**.** If
29830 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
29840 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72  nt does not curr
29850 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61  ently point to a
29860 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69   valid row, or i
29870 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  f the.** column 
29880 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
29890 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c  range, the resul
298a0 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  t is undefined..
298b0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
298c0 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61  s may only be ca
298d0 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f  lled when the mo
298e0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
298f0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
29900 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
29910 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
29920 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b  and neither.** [
29930 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
29940 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69   nor [sqlite3_fi
29950 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62  nalize()] have b
29960 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65  een called subse
29970 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61  quently..** If a
29980 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
29990 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
299a0 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72  after [sqlite3_r
299b0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
299c0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
299d0 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c  )] or after [sql
299e0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
299f0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d   returned.** som
29a00 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
29a10 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  n [SQLITE_ROW], 
29a20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
29a30 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
29a40 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
29a50 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
29a60 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
29a70 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a  e3_finalize()].*
29a80 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  * are called fro
29a90 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68  m a different th
29aa0 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f  read while any o
29ab0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
29ac0 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c  .** are pending,
29ad0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
29ae0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
29af0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
29b00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
29b10 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
29b20 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
29b30 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
29b40 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ype code] for th
29b50 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74  e initial data t
29b60 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65  ype.** of the re
29b70 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54  sult column.  ^T
29b80 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75  he returned valu
29b90 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  e is one of [SQL
29ba0 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a  ITE_INTEGER],.**
29bb0 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
29bc0 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
29bd0 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f  [SQLITE_BLOB], o
29be0 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e  r [SQLITE_NULL].
29bf0 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72    The value.** r
29c00 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
29c10 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
29c20 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67   is only meaning
29c30 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a  ful if no type.*
29c40 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61  * conversions ha
29c50 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64  ve occurred as d
29c60 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20  escribed below. 
29c70 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f   After a type co
29c80 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65  nversion,.** the
29c90 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
29ca0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
29cb0 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65  n_type() is unde
29cc0 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a  fined.  Future.*
29cd0 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  * versions of SQ
29ce0 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20  Lite may change 
29cf0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
29d00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
29d10 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  ype().** followi
29d20 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  ng a type conver
29d30 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  sion..**.** ^If 
29d40 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
29d50 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74  BLOB or UTF-8 st
29d60 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
29d70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
29d80 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  es().** routine 
29d90 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
29da0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
29db0 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
29dc0 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
29dd0 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31  esult is a UTF-1
29de0 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  6 string, then s
29df0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
29e00 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  tes() converts.*
29e10 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
29e20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72  UTF-8 and then r
29e30 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
29e40 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
29e50 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
29e60 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
29e70 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
29e80 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65  lumn_bytes() use
29e90 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
29ea0 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
29eb0 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
29ec0 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  to a UTF-8 strin
29ed0 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
29ee0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
29ef0 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
29f00 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
29f10 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
29f20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
29f30 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75  umn_bytes() retu
29f40 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
29f50 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
29f60 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
29f70 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  16 string then t
29f80 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
29f90 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72  n_bytes16().** r
29fa0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
29fb0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
29fc0 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
29fd0 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
29fe0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
29ff0 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20  a UTF-8 string, 
2a000 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2a010 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f  umn_bytes16() co
2a020 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
2a030 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61  ring to UTF-16 a
2a040 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
2a050 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2a060 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
2a070 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
2a080 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
2a090 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2a0a0 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20  tes16() uses.** 
2a0b0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
2a0c0 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
2a0d0 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
2a0e0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e  UTF-16 string an
2a0f0 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
2a100 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2a110 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
2a120 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2a130 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
2a140 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a150 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e  bytes16() return
2a160 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s zero..**.** ^T
2a170 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
2a180 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
2a190 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
2a1a0 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nd .** [sqlite3_
2a1b0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2a1c0 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65  ] do not include
2a1d0 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
2a1e0 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64  ators at the end
2a1f0 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e  .** of the strin
2a200 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79  g.  ^For clarity
2a210 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74  : the values ret
2a220 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
2a230 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2a240 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  s()] and [sqlite
2a250 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2a260 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62  ()] are the numb
2a270 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69  er of.** bytes i
2a280 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f  n the string, no
2a290 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
2a2a0 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
2a2b0 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72  * ^Strings retur
2a2c0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2a2d0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64  olumn_text() and
2a2e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a2f0 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65  text16(),.** eve
2a300 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c  n empty strings,
2a310 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f   are always zero
2a320 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
2a330 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  he return.** val
2a340 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2a350 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
2a360 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
2a370 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70  BLOB is a NULL p
2a380 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
2a390 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  he object return
2a3a0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
2a3b0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
2a3c0 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  s an.** [unprote
2a3d0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2a3e0 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20  ue] object.  An 
2a3f0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2a400 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2a410 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
2a420 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74  used with [sqlit
2a430 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
2a440 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
2a450 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  sult_value()]..*
2a460 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74  * If the [unprot
2a470 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2a480 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  lue] object retu
2a490 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
2a4a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
2a4b0 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61  ()] is used in a
2a4c0 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e  ny other way, in
2a4d0 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a  cluding calls.**
2a4e0 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
2a4f0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2a500 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  _int()], [sqlite
2a510 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
2a520 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
2a530 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
2a540 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
2a550 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
2a560 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2a570 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20  ines attempt to 
2a580 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
2a590 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69  e where appropri
2a5a0 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78  ate.  ^For.** ex
2a5b0 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e  ample, if the in
2a5c0 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
2a5d0 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61  ation is FLOAT a
2a5e0 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74  nd a text result
2a5f0 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64  .** is requested
2a600 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  , [sqlite3_snpri
2a610 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69  ntf()] is used i
2a620 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72  nternally to per
2a630 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76  form the.** conv
2a640 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63  ersion automatic
2a650 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c  ally.  ^(The fol
2a660 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74  lowing table det
2a670 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73  ails the convers
2a680 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ions.** that are
2a690 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20   applied:.**.** 
2a6a0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
2a6b0 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
2a6c0 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49  ">.** <tr><th> I
2a6d0 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20  nternal<br>Type 
2a6e0 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62  <th> Requested<b
2a6f0 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e  r>Type <th>  Con
2a700 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  version.**.** <t
2a710 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2a720 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2a730 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a  td> Result is 0.
2a740 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
2a750 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  L    <td>  FLOAT
2a760 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
2a770 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74  is 0.0.** <tr><t
2a780 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2a790 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2a7a0 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
2a7b0 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
2a7c0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2a7d0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2a7e0 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
2a7f0 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
2a800 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
2a810 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2a820 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
2a830 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
2a840 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
2a850 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
2a860 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
2a870 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
2a880 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
2a890 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
2a8a0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
2a8b0 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
2a8c0 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
2a8d0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
2a8e0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
2a8f0 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74  nvert from float
2a900 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c   to integer.** <
2a910 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
2a920 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2a930 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
2a940 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
2a950 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
2a960 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
2a970 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
2a980 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a  as FLOAT->TEXT.*
2a990 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
2a9a0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
2a9b0 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69     <td> Use atoi
2a9c0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
2a9d0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
2a9e0 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20  OAT    <td> Use 
2a9f0 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
2aa00 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
2aa10 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2aa20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72  No change.** <tr
2aa30 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
2aa40 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
2aa50 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
2aa60 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69  XT then use atoi
2aa70 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
2aa80 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
2aa90 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
2aaa0 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
2aab0 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   use atof().** <
2aac0 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
2aad0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2aae0 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
2aaf0 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
2ab00 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
2ab10 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
2ab20 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  >)^.**.** The ta
2ab30 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20  ble above makes 
2ab40 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61  reference to sta
2ab50 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20  ndard C library 
2ab60 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29  functions atoi()
2ab70 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20  .** and atof(). 
2ab80 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74   SQLite does not
2ab90 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73   really use thes
2aba0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74  e functions.  It
2abb0 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20   has its.** own 
2abc0 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72  equivalent inter
2abd0 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54  nal routines.  T
2abe0 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74  he atoi() and at
2abf0 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a  of() names are.*
2ac00 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61  * used in the ta
2ac10 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20  ble for brevity 
2ac20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79  and because they
2ac30 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f   are familiar to
2ac40 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72   most.** C progr
2ac50 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  ammers..**.** No
2ac60 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70  te that when typ
2ac70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63  e conversions oc
2ac80 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65  cur, pointers re
2ac90 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a  turned by prior.
2aca0 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
2acb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2acc0 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
2acd0 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72  n_text(), and/or
2ace0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2acf0 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20  mn_text16() may 
2ad00 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  be invalidated..
2ad10 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69  ** Type conversi
2ad20 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20  ons and pointer 
2ad30 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69  invalidations mi
2ad40 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ght occur.** in 
2ad50 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
2ad60 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ses:.**.** <ul>.
2ad70 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
2ad80 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61  ial content is a
2ad90 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65   BLOB and sqlite
2ada0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2adb0 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
2adc0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2add0 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41  () is called.  A
2ade0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
2adf0 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e   might.**      n
2ae00 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20  eed to be added 
2ae10 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f  to the string.</
2ae20 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
2ae30 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
2ae40 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e  is UTF-8 text an
2ae50 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2ae60 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a  _bytes16() or.**
2ae70 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
2ae80 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
2ae90 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
2aea0 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
2aeb0 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
2aec0 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a  to UTF-16.</li>.
2aed0 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
2aee0 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
2aef0 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73  TF-16 text and s
2af00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2af10 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  tes() or.**     
2af20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2af30 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64  text() is called
2af40 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
2af50 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
2af60 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
2af70 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  8.</li>.** </ul>
2af80 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69  .**.** ^Conversi
2af90 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d  ons between UTF-
2afa0 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c  16be and UTF-16l
2afb0 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e  e are always don
2afc0 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64  e in place and d
2afd0 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64  o.** not invalid
2afe0 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e  ate a prior poin
2aff0 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  ter, though of c
2b000 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e  ourse the conten
2b010 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a  t of the buffer.
2b020 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f  ** that the prio
2b030 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65  r pointer refere
2b040 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62  nces will have b
2b050 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f  een modified.  O
2b060 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66  ther kinds.** of
2b070 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20   conversion are 
2b080 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68  done in place wh
2b090 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c  en it is possibl
2b0a0 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73  e, but sometimes
2b0b0 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74   they.** are not
2b0c0 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e   possible and in
2b0d0 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69   those cases pri
2b0e0 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20  or pointers are 
2b0f0 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a  invalidated..**.
2b100 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e  ** The safest an
2b110 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d  d easiest to rem
2b120 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20  ember policy is 
2b130 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20  to invoke these 
2b140 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f  routines.** in o
2b150 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
2b160 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ing ways:.**.** 
2b170 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  <ul>.**  <li>sql
2b180 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2b190 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
2b1a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2b1b0 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
2b1c0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
2b1d0 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65  n_blob() followe
2b1e0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2b1f0 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
2b200 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
2b210 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2b220 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
2b230 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2b240 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  s16()</li>.** </
2b250 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  ul>.**.** In oth
2b260 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68  er words, you sh
2b270 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65  ould call sqlite
2b280 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
2b290 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2b2a0 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71  mn_blob(), or sq
2b2b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2b2c0 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66  t16() first to f
2b2d0 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a  orce the result.
2b2e0 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  ** into the desi
2b2f0 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e  red format, then
2b300 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
2b310 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
2b320 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
2b330 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
2b340 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f   find the size o
2b350 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44  f the result.  D
2b360 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a  o not mix calls.
2b370 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
2b380 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73  lumn_text() or s
2b390 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2b3a0 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20  ob() with calls 
2b3b0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
2b3c0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20  lumn_bytes16(), 
2b3d0 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63  and do not mix c
2b3e0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2b3f0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a  column_text16().
2b400 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  ** with calls to
2b410 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2b420 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  bytes()..**.** ^
2b430 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  The pointers ret
2b440 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20  urned are valid 
2b450 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e  until a type con
2b460 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61  version occurs a
2b470 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61  s.** described a
2b480 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b  bove, or until [
2b490 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2b4a0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
2b4b0 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
2b4c0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2b4d0 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65  is called.  ^The
2b4e0 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73   memory space us
2b4f0 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e  ed to hold strin
2b500 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20  gs.** and BLOBs 
2b510 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74  is freed automat
2b520 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e  ically.  Do <b>n
2b530 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20  ot</b> pass the 
2b540 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
2b550 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
2b560 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  lumn_blob()], [s
2b570 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2b580 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f  xt()], etc. into
2b590 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
2b5a0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  e()]..**.** ^(If
2b5b0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
2b5c0 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
2b5d0 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61  s during the eva
2b5e0 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a  luation of any.*
2b5f0 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  * of these routi
2b600 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76  nes, a default v
2b610 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
2b620 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  .  The default v
2b630 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65  alue.** is eithe
2b640 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c  r the integer 0,
2b650 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
2b660 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20  int number 0.0, 
2b670 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  or a NULL.** poi
2b680 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e  nter.  Subsequen
2b690 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
2b6a0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77  te3_errcode()] w
2b6b0 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53  ill return.** [S
2b6c0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a  QLITE_NOMEM].)^.
2b6d0 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
2b6e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2b6f0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
2b700 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
2b710 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2b720 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74  bytes(sqlite3_st
2b730 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2b740 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2b750 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  mn_bytes16(sqlit
2b760 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2b770 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69  ol);.double sqli
2b780 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c  te3_column_doubl
2b790 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2b7a0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
2b7b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
2b7c0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
2b7d0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
2b7e0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
2b7f0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28  e3_column_int64(
2b800 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2b810 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20  nt iCol);.const 
2b820 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
2b830 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2b840 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
2b850 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
2b860 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2b870 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73  _column_text16(s
2b880 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2b890 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
2b8a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2b8b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2b8c0 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
2b8d0 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65  e3_value *sqlite
2b8e0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73  3_column_value(s
2b8f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2b900 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t iCol);../*.** 
2b910 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f  CAPI3REF: Destro
2b920 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  y A Prepared Sta
2b930 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
2b940 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2b950 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63  _finalize() func
2b960 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
2b970 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70  o delete a [prep
2b980 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2b990 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
2b9a0 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69   recent evaluati
2b9b0 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d  on of the statem
2b9c0 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20  ent encountered 
2b9d0 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20  no errors.** or 
2b9e0 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
2b9f0 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65   is never been e
2ba00 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73  valuated, then s
2ba10 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2ba20 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c  ) returns.** SQL
2ba30 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65  ITE_OK.  ^If the
2ba40 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61   most recent eva
2ba50 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65  luation of state
2ba60 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74  ment S failed, t
2ba70 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  hen.** sqlite3_f
2ba80 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72  inalize(S) retur
2ba90 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 61  ns the appropria
2baa0 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  te [error code] 
2bab0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
2bac0 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a  error code]..**.
2bad0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2bae0 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74  finalize(S) rout
2baf0 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ine can be calle
2bb00 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64  d at any point d
2bb10 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66  uring.** the lif
2bb20 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70  e cycle of [prep
2bb30 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2bb40 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61  S:.** before sta
2bb50 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72  tement S is ever
2bb60 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65   evaluated, afte
2bb70 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  r.** one or more
2bb80 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
2bb90 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20  e3_reset()], or 
2bba0 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a  after any call.*
2bbb0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  * to [sqlite3_st
2bbc0 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73  ep()] regardless
2bbd0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
2bbe0 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ot the statement
2bbf0 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   has.** complete
2bc00 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a  d execution..**.
2bc10 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c  ** ^Invoking sql
2bc20 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
2bc30 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  on a NULL pointe
2bc40 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20  r is a harmless 
2bc50 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  no-op..**.** The
2bc60 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
2bc70 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79  t finalize every
2bc80 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2bc90 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74  ment] in order t
2bca0 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75  o avoid.** resou
2bcb0 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69  rce leaks.  It i
2bcc0 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 72  s a grievous err
2bcd0 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69  or for the appli
2bce0 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f  cation to try to
2bcf0 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72   use.** a prepar
2bd00 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74  ed statement aft
2bd10 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66  er it has been f
2bd20 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75  inalized.  Any u
2bd30 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64  se of a prepared
2bd40 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66  .** statement af
2bd50 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
2bd60 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65  finalized can re
2bd70 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
2bd80 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72  d and.** undesir
2bd90 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75  able behavior su
2bda0 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 20  ch as segfaults 
2bdb0 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 74  and heap corrupt
2bdc0 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ion..*/.int sqli
2bdd0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c  te3_finalize(sql
2bde0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2bdf0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2be00 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70  EF: Reset A Prep
2be10 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
2be20 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
2be30 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20  sqlite3_reset() 
2be40 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
2be50 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70  ed to reset a [p
2be60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2be70 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63  t].** object bac
2be80 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
2be90 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f   state, ready to
2bea0 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e   be re-executed.
2beb0 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61  .** ^Any SQL sta
2bec0 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73  tement variables
2bed0 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73   that had values
2bee0 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75   bound to them u
2bef0 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  sing.** the [sql
2bf00 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
2bf10 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2bf20 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68  ) API] retain th
2bf30 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55  eir values..** U
2bf40 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61  se [sqlite3_clea
2bf50 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f  r_bindings()] to
2bf60 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69   reset the bindi
2bf70 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ngs..**.** ^The 
2bf80 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2bf90 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73  )] interface res
2bfa0 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65  ets the [prepare
2bfb0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a  d statement] S.*
2bfc0 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65  * back to the be
2bfd0 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70  ginning of its p
2bfe0 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  rogram..**.** ^I
2bff0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2c000 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2c010 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
2c020 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2c030 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65   statement] S re
2c040 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
2c050 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OW] or [SQLITE_D
2c060 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b  ONE],.** or if [
2c070 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2c080 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72   has never befor
2c090 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e  e been called on
2c0a0 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c   S,.** then [sql
2c0b0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
2c0c0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
2c0d0 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  K]..**.** ^If th
2c0e0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
2c0f0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2c100 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
2c110 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2c120 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61  tement] S indica
2c130 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68  ted an error, th
2c140 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  en.** [sqlite3_r
2c150 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
2c160 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
2c170 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a  [error code]..**
2c180 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
2c190 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
2c1a0 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63  rface does not c
2c1b0 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73  hange the values
2c1c0 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69  .** of any [sqli
2c1d0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69  te3_bind_blob|bi
2c1e0 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b  ndings] on the [
2c1f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2c200 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71  nt] S..*/.int sq
2c210 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69  lite3_reset(sqli
2c220 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2c230 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2c240 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64  F: Create Or Red
2c250 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69  efine SQL Functi
2c260 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
2c270 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   {function creat
2c280 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a  ion routines}.**
2c290 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
2c2a0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2c2b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a  SQL function}.**
2c2c0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
2c2d0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2c2e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  SQL functions}.*
2c2f0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  *.** ^These func
2c300 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76  tions (collectiv
2c310 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75  ely known as "fu
2c320 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
2c330 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72  routines").** ar
2c340 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51  e used to add SQ
2c350 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
2c360 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20  ggregates or to 
2c370 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68  redefine the beh
2c380 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73  avior.** of exis
2c390 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f  ting SQL functio
2c3a0 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
2c3b0 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66  .  The only diff
2c3c0 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a  erences between.
2c3d0 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ** these routine
2c3e0 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20 65  s are the text e
2c3f0 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64  ncoding expected
2c400 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f   for.** the seco
2c410 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  nd parameter (th
2c420 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75  e name of the fu
2c430 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65  nction being cre
2c440 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ated).** and the
2c450 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73   presence or abs
2c460 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 75  ence of a destru
2c470 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f  ctor callback fo
2c480 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  r.** the applica
2c490 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
2c4a0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  r..**.** ^The fi
2c4b0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
2c4c0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2c4d0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68  onnection] to wh
2c4e0 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66  ich the SQL.** f
2c4f0 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  unction is to be
2c500 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20   added.  ^If an 
2c510 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73  application uses
2c520 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64   more than one d
2c530 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
2c540 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69  ction then appli
2c550 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2c560 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73  QL functions mus
2c570 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f  t be added.** to
2c580 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
2c590 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61  onnection separa
2c5a0 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tely..**.** ^The
2c5b0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2c5c0 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
2c5d0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2c5e0 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20  n to be created 
2c5f0 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e  or.** redefined.
2c600 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66    ^The length of
2c610 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d   the name is lim
2c620 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65  ited to 255 byte
2c630 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20  s in a UTF-8.** 
2c640 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20  representation, 
2c650 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
2c660 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
2c670 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  .  ^Note that th
2c680 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68  e name.** length
2c690 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46   limit is in UTF
2c6a0 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68  -8 bytes, not ch
2c6b0 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46  aracters nor UTF
2c6c0 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20  -16 bytes.  .** 
2c6d0 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20  ^Any attempt to 
2c6e0 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f  create a functio
2c6f0 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20  n with a longer 
2c700 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73  name.** will res
2c710 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d  ult in [SQLITE_M
2c720 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74  ISUSE] being ret
2c730 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
2c740 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2c750 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74  r (nArg).** is t
2c760 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  he number of arg
2c770 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20  uments that the 
2c780 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
2c790 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b  ** aggregate tak
2c7a0 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72  es. ^If this par
2c7b0 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68  ameter is -1, th
2c7c0 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  en the SQL funct
2c7d0 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
2c7e0 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79  ate may take any
2c7f0 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
2c800 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 61  ents between 0 a
2c810 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20  nd the limit.** 
2c820 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  set by [sqlite3_
2c830 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c  limit]([SQLITE_L
2c840 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
2c850 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 69  G]).  If the thi
2c860 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
2c870 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20  is less than -1 
2c880 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
2c890 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 68  127 then the beh
2c8a0 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65  avior is.** unde
2c8b0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2c8c0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2c8d0 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70  er, eTextRep, sp
2c8e0 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20  ecifies what.** 
2c8f0 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74  [SQLITE_UTF8 | t
2c900 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68  ext encoding] th
2c910 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  is SQL function 
2c920 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69  prefers for.** i
2c930 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ts parameters.  
2c940 45 76 65 72 79 20 53 51 4c 20 66 75 6e 63 74 69  Every SQL functi
2c950 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
2c960 6e 20 6d 75 73 74 20 62 65 20 61 62 6c 65 20 74  n must be able t
2c970 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20 55  o work.** with U
2c980 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20  TF-8, UTF-16le, 
2c990 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75  or UTF-16be.  Bu
2c9a0 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74  t some implement
2c9b0 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a  ations may be.**
2c9c0 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20   more efficient 
2c9d0 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e  with one encodin
2c9e0 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20  g than another. 
2c9f0 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e   ^An application
2ca00 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73   may.** invoke s
2ca10 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2ca20 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69  nction() or sqli
2ca30 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2ca40 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65  ion16() multiple
2ca50 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74  .** times with t
2ca60 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
2ca70 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72   but with differ
2ca80 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54  ent values of eT
2ca90 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e  extRep..** ^When
2caa0 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
2cab0 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
2cac0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61   same function a
2cad0 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51  re available, SQ
2cae0 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63  Lite.** will pic
2caf0 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69  k the one that i
2cb00 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73  nvolves the leas
2cb10 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61  t amount of data
2cb20 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20   conversion..** 
2cb30 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79  If there is only
2cb40 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d   a single implem
2cb50 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64  entation which d
2cb60 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61  oes not care wha
2cb70 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69  t text.** encodi
2cb80 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  ng is used, then
2cb90 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
2cba0 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b  ment should be [
2cbb0 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a  SQLITE_ANY]..**.
2cbc0 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70  ** ^(The fifth p
2cbd0 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61  arameter is an a
2cbe0 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72  rbitrary pointer
2cbf0 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  .  The implement
2cc00 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  ation of the.** 
2cc10 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69  function can gai
2cc20 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73  n access to this
2cc30 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b   pointer using [
2cc40 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
2cc50 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  a()].)^.**.** ^T
2cc60 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74  he sixth, sevent
2cc70 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61 72  h and eighth par
2cc80 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20  ameters, xFunc, 
2cc90 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
2cca0 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  , are.** pointer
2ccb0 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20  s to C-language 
2ccc0 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69  functions that i
2ccd0 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
2cce0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
2ccf0 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63  aggregate. ^A sc
2cd00 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
2cd10 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
2cd20 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2cd30 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c  the xFunc.** cal
2cd40 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c  lback only; NULL
2cd50 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62   pointers must b
2cd60 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
2cd70 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
2cd80 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
2cd90 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51  ^An aggregate SQ
2cda0 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
2cdb0 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
2cdc0 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a  ation of xStep.*
2cdd0 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64  * and xFinal and
2cde0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75   NULL pointer mu
2cdf0 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f 72  st be passed for
2ce00 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65   xFunc. ^To dele
2ce10 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a  te an existing.*
2ce20 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  * SQL function o
2ce30 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73  r aggregate, pas
2ce40 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  s NULL pointers 
2ce50 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75  for all three fu
2ce60 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  nction.** callba
2ce70 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  cks..**.** ^(If 
2ce80 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65  the ninth parame
2ce90 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ter to sqlite3_c
2cea0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
2ceb0 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  2() is not NULL,
2cec0 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64  .** then it is d
2ced0 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68  estructor for th
2cee0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
2cef0 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20  ta pointer. .** 
2cf00 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
2cf10 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74  s invoked when t
2cf20 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64  he function is d
2cf30 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 62  eleted, either b
2cf40 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c  y being.** overl
2cf50 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68  oaded or when th
2cf60 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2cf70 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a  ction closes.)^.
2cf80 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 74  ** ^The destruct
2cf90 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b  or is also invok
2cfa0 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74  ed if the call t
2cfb0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65  o.** sqlite3_cre
2cfc0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
2cfd0 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65  ) fails..** ^Whe
2cfe0 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  n the destructor
2cff0 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   callback of the
2d000 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72   tenth parameter
2d010 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a   is invoked, it.
2d020 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 73  ** is passed a s
2d030 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
2d040 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f  hich is a copy o
2d050 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
2d060 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74  n data .** point
2d070 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65  er which was the
2d080 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72   fifth parameter
2d090 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61   to sqlite3_crea
2d0a0 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
2d0b0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70  ..**.** ^It is p
2d0c0 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69  ermitted to regi
2d0d0 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d  ster multiple im
2d0e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
2d0f0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e   the same.** fun
2d100 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20  ctions with the 
2d110 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69  same name but wi
2d120 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72  th either differ
2d130 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a  ing numbers of.*
2d140 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64  * arguments or d
2d150 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72  iffering preferr
2d160 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
2d170 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  s.  ^SQLite will
2d180 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c   use.** the impl
2d190 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20  ementation that 
2d1a0 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74  most closely mat
2d1b0 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20  ches the way in 
2d1c0 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c  which the.** SQL
2d1d0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65   function is use
2d1e0 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  d.  ^A function 
2d1f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2d200 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69  ith a non-negati
2d210 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d  ve.** nArg param
2d220 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72  eter is a better
2d230 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
2d240 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
2d250 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20  ation with.** a 
2d260 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20  negative nArg.  
2d270 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
2d280 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
2d290 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a  text encoding.**
2d2a0 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74   matches the dat
2d2b0 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69  abase encoding i
2d2c0 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61  s a better.** ma
2d2d0 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
2d2e0 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
2d2f0 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72  coding is differ
2d300 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e  ent.  .** ^A fun
2d310 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
2d320 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
2d330 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55  nce is between U
2d340 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36  TF16le and UTF16
2d350 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65  be.** is a close
2d360 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
2d370 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
2d380 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
2d390 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77  rence is.** betw
2d3a0 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46  een UTF8 and UTF
2d3b0 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74  16..**.** ^Built
2d3c0 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  -in functions ma
2d3d0 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20  y be overloaded 
2d3e0 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  by new applicati
2d3f0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2d400 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  ions..**.** ^An 
2d410 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2d420 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ned function is 
2d430 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c  permitted to cal
2d440 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  l other.** SQLit
2d450 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48  e interfaces.  H
2d460 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c  owever, such cal
2d470 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63  ls must not.** c
2d480 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73  lose the databas
2d490 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72  e connection nor
2d4a0 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73   finalize or res
2d4b0 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a  et the prepared.
2d4c0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  ** statement in 
2d4d0 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69  which the functi
2d4e0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
2d4f0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  /.int sqlite3_cr
2d500 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20  eate_function(. 
2d510 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
2d520 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
2d530 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
2d540 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
2d550 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
2d560 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
2d570 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
2d580 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2d590 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2d5a0 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
2d5b0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2d5c0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2d5d0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
2d5e0 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
2d5f0 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  ext*).);.int sql
2d600 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2d610 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
2d620 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76  3 *db,.  const v
2d630 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  oid *zFunctionNa
2d640 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
2d650 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
2d660 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
2d670 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
2d680 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2d690 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2d6a0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
2d6b0 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
2d6c0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2d6d0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2d6e0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
2d6f0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
2d700 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
2d710 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
2d720 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2d730 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2d740 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
2d750 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
2d760 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
2d770 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
2d780 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
2d790 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
2d7a0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
2d7b0 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
2d7c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2d7d0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2d7e0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
2d7f0 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
2d800 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64  ontext*),.  void
2d810 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
2d820 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
2d830 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f  I3REF: Text Enco
2d840 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  dings.**.** Thes
2d850 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e  e constant defin
2d860 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20  e integer codes 
2d870 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74  that represent t
2d880 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65  he various.** te
2d890 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70  xt encodings sup
2d8a0 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
2d8b0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
2d8c0 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20  ITE_UTF8        
2d8d0 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
2d8e0 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20  ITE_UTF16LE     
2d8f0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
2d900 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20  ITE_UTF16BE     
2d910 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
2d920 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20  ITE_UTF16       
2d930 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e     4    /* Use n
2d940 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
2d950 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2d960 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20  TE_ANY          
2d970 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    5    /* sqlite
2d980 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2d990 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  n only */.#defin
2d9a0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41  e SQLITE_UTF16_A
2d9b0 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20  LIGNED  8    /* 
2d9c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2d9d0 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  ollation only */
2d9e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2d9f0 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e  : Deprecated Fun
2da00 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43  ctions.** DEPREC
2da10 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ATED.**.** These
2da20 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b   functions are [
2da30 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e  deprecated].  In
2da40 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61   order to mainta
2da50 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  in.** backwards 
2da60 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69  compatibility wi
2da70 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74  th older code, t
2da80 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63  hese functions c
2da90 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62  ontinue .** to b
2daa0 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f  e supported.  Ho
2dab0 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69  wever, new appli
2dac0 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61  cations should a
2dad0 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20  void.** the use 
2dae0 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
2daf0 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63  ns.  To help enc
2db00 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f  ourage people to
2db10 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20   avoid.** using 
2db20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c  these functions,
2db30 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e   we are not goin
2db40 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68  g to tell you wh
2db50 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23  at they do..*/.#
2db60 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  ifndef SQLITE_OM
2db70 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51  IT_DEPRECATED.SQ
2db80 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
2db90 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72  int sqlite3_aggr
2dba0 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69  egate_count(sqli
2dbb0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53  te3_context*);.S
2dbc0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
2dbd0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70   int sqlite3_exp
2dbe0 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d  ired(sqlite3_stm
2dbf0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
2dc00 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
2dc10 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64  e3_transfer_bind
2dc20 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
2dc30 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  t*, sqlite3_stmt
2dc40 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
2dc50 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
2dc60 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72  3_global_recover
2dc70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44  (void);.SQLITE_D
2dc80 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73  EPRECATED void s
2dc90 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c  qlite3_thread_cl
2dca0 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c  eanup(void);.SQL
2dcb0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
2dcc0 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  nt sqlite3_memor
2dcd0 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28  y_alarm(void(*)(
2dce0 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
2dcf0 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73  t64,int),void*,s
2dd00 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23  qlite3_int64);.#
2dd10 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
2dd20 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67  I3REF: Obtaining
2dd30 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61   SQL Function Pa
2dd40 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a  rameter Values.*
2dd50 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75  *.** The C-langu
2dd60 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  age implementati
2dd70 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69  on of SQL functi
2dd80 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
2dd90 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20  es uses.** this 
2dda0 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65  set of interface
2ddb0 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63   routines to acc
2ddc0 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65  ess the paramete
2ddd0 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74  r values on.** t
2dde0 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  he function or a
2ddf0 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ggregate..**.** 
2de00 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73  The xFunc (for s
2de10 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29  calar functions)
2de20 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61   or xStep (for a
2de30 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d  ggregates) param
2de40 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c  eters.** to [sql
2de50 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2de60 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
2de70 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2de80 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66  tion16()].** def
2de90 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  ine callbacks th
2dea0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
2deb0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
2dec0 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a  nd aggregates..*
2ded0 2a 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65  * The 3rd parame
2dee0 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c  ter to these cal
2def0 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72  lbacks is an arr
2df00 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
2df10 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20  o.** [protected 
2df20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2df30 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69  bjects.  There i
2df40 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76  s one [sqlite3_v
2df50 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72  alue] object for
2df60 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74  .** each paramet
2df70 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75  er to the SQL fu
2df80 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72  nction.  These r
2df90 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
2dfa0 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76   to.** extract v
2dfb0 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b  alues from the [
2dfc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2dfd0 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  bjects..**.** Th
2dfe0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
2dff0 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f  k only with [pro
2e000 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2e010 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
2e020 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
2e030 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69   use these routi
2e040 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f  nes on an [unpro
2e050 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2e060 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  alue].** object 
2e070 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
2e080 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
2e090 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
2e0a0 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c  ines work just l
2e0b0 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ike the correspo
2e0c0 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63  nding [column ac
2e0d0 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a  cess functions].
2e0e0 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 20  ** except that  
2e0f0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
2e100 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72  ake a single [pr
2e110 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2e120 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a  value] object.**
2e130 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64   pointer instead
2e140 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73   of a [sqlite3_s
2e150 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e  tmt*] pointer an
2e160 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c  d an integer col
2e170 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a  umn number..**.*
2e180 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
2e190 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e  alue_text16() in
2e1a0 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73  terface extracts
2e1b0 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
2e1c0 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76  .** in the nativ
2e1d0 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20  e byte-order of 
2e1e0 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65  the host machine
2e1f0 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
2e200 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
2e210 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
2e220 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29  value_text16le()
2e230 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65   interfaces.** e
2e240 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74  xtract UTF-16 st
2e250 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64  rings as big-end
2e260 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65  ian and little-e
2e270 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65  ndian respective
2e280 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ly..**.** ^(The 
2e290 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
2e2a0 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74  meric_type() int
2e2b0 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
2e2c0 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65  to apply.** nume
2e2d0 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20  ric affinity to 
2e2e0 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73  the value.  This
2e2f0 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61   means that an a
2e300 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64  ttempt is.** mad
2e310 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  e to convert the
2e320 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74   value to an int
2e330 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67  eger or floating
2e340 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73   point.  If.** s
2e350 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  uch a conversion
2e360 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74   is possible wit
2e370 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66  hout loss of inf
2e380 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68  ormation (in oth
2e390 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20  er.** words, if 
2e3a0 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73  the value is a s
2e3b0 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73  tring that looks
2e3c0 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a   like a number).
2e3d0 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76  ** then the conv
2e3e0 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72  ersion is perfor
2e3f0 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  med.  Otherwise 
2e400 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  no conversion oc
2e410 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51  curs..** The [SQ
2e420 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
2e430 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63  atatype] after c
2e440 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74  onversion is ret
2e450 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50  urned.)^.**.** P
2e460 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63  lease pay partic
2e470 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74  ular attention t
2e480 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20  o the fact that 
2e490 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75  the pointer retu
2e4a0 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  rned.** from [sq
2e4b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
2e4c0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
2e4d0 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a  lue_text()], or.
2e4e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
2e4f0 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20  e_text16()] can 
2e500 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62  be invalidated b
2e510 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63  y a subsequent c
2e520 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2e530 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
2e540 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
2e550 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73  e_bytes16()], [s
2e560 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2e570 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
2e580 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2e590 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  6()]..**.** Thes
2e5a0 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
2e5b0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
2e5c0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61  he same thread a
2e5d0 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  s.** the SQL fun
2e5e0 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c  ction that suppl
2e5f0 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ied the [sqlite3
2e600 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74  _value*] paramet
2e610 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  ers..*/.const vo
2e620 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
2e630 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76  e_blob(sqlite3_v
2e640 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
2e650 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
2e660 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2e670 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
2e680 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  ue_bytes16(sqlit
2e690 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62  e3_value*);.doub
2e6a0 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le sqlite3_value
2e6b0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
2e6c0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
2e6d0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73  ite3_value_int(s
2e6e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2e6f0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
2e700 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36  lite3_value_int6
2e710 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  4(sqlite3_value*
2e720 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  );.const unsigne
2e730 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
2e740 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74  value_text(sqlit
2e750 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
2e760 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2e770 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c  value_text16(sql
2e780 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
2e790 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2e7a0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
2e7b0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2e7c0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2e7d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2e7e0 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16be(sqlite3_val
2e7f0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
2e800 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c  3_value_type(sql
2e810 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
2e820 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
2e830 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c  numeric_type(sql
2e840 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f  ite3_value*);../
2e850 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2e860 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20  btain Aggregate 
2e870 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
2e880 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74  .**.** Implement
2e890 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67  ations of aggreg
2e8a0 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
2e8b0 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f  s use this.** ro
2e8c0 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74  utine to allocat
2e8d0 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f  e memory for sto
2e8e0 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65  ring their state
2e8f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
2e900 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69  st time the sqli
2e910 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2e920 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69  ntext(C,N) routi
2e930 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a  ne is called .**
2e940 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
2e950 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  r aggregate func
2e960 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  tion, SQLite.** 
2e970 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d  allocates N of m
2e980 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75  emory, zeroes ou
2e990 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61  t that memory, a
2e9a0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
2e9b0 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e  nter.** to the n
2e9c0 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73  ew memory. ^On s
2e9d0 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
2e9e0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  uent calls to.**
2e9f0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
2ea00 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72  te_context() for
2ea10 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
2ea20 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73  ate function ins
2ea30 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61  tance,.** the sa
2ea40 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74  me buffer is ret
2ea50 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f  urned.  Sqlite3_
2ea60 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2ea70 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a  t() is normally.
2ea80 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66  ** called once f
2ea90 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69  or each invocati
2eaa0 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20  on of the xStep 
2eab0 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65  callback and the
2eac0 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69  n one.** last ti
2ead0 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e  me when the xFin
2eae0 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  al callback is i
2eaf0 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20  nvoked.  ^(When 
2eb00 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a  no rows match.**
2eb10 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75   an aggregate qu
2eb20 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29  ery, the xStep()
2eb30 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   callback of the
2eb40 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
2eb50 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ion.** implement
2eb60 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63  ation is never c
2eb70 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c  alled and xFinal
2eb80 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61  () is called exa
2eb90 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e  ctly once..** In
2eba0 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71   those cases, sq
2ebb0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2ebc0 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20  context() might 
2ebd0 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68  be called for th
2ebe0 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20  e.** first time 
2ebf0 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e  from within xFin
2ec00 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  al().)^.**.** ^T
2ec10 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
2ec20 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
2ec30 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
2ec40 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2ec50 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73   if N is.** less
2ec60 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
2ec70 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d  o zero or if a m
2ec80 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20 65  emory allocate e
2ec90 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a  rror occurs..**.
2eca0 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20  ** ^(The amount 
2ecb0 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74  of space allocat
2ecc0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67  ed by sqlite3_ag
2ecd0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2ece0 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72  C,N) is.** deter
2ecf0 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70  mined by the N p
2ed00 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73  arameter on firs
2ed10 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  t successful cal
2ed20 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65  l.  Changing the
2ed30 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69  .** value of N i
2ed40 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
2ed50 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67  l to sqlite3_agg
2ed60 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
2ed70 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73   within.** the s
2ed80 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75  ame aggregate fu
2ed90 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20  nction instance 
2eda0 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20  will not resize 
2edb0 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  the memory.** al
2edc0 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a  location.)^.**.*
2edd0 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61  * ^SQLite automa
2ede0 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68  tically frees th
2edf0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
2ee00 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65  ed by .** sqlite
2ee10 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2ee20 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 61  ext() when the a
2ee30 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20 63  ggregate query c
2ee40 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20  oncludes..**.** 
2ee50 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
2ee60 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f  ter must be a co
2ee70 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  py of the.** [sq
2ee80 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20  lite3_context | 
2ee90 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e  SQL function con
2eea0 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68  text] that is th
2eeb0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2eec0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65  r.** to the xSte
2eed0 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  p or xFinal call
2eee0 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61  back routine tha
2eef0 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
2ef00 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75   aggregate.** fu
2ef10 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
2ef20 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
2ef30 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
2ef40 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
2ef50 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
2ef60 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
2ef70 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
2ef80 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
2ef90 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2efa0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
2efb0 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65  text*, int nByte
2efc0 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
2efd0 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46  REF: User Data F
2efe0 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  or Functions.**.
2eff0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2f000 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65  user_data() inte
2f010 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2f020 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
2f030 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20  ointer that was 
2f040 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61  the pUserData pa
2f050 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68  rameter (the 5th
2f060 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
2f070 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
2f080 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2f090 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
2f0a0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2f0b0 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
2f0c0 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
2f0d0 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
2f0e0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
2f0f0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
2f100 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
2f110 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
2f120 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
2f130 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
2f140 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
2f150 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2f160 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
2f170 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
2f180 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74  _user_data(sqlit
2f190 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
2f1a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2f1b0 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2f1c0 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  on For Functions
2f1d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2f1e0 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
2f1f0 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63  andle() interfac
2f200 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
2f210 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
2f220 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62  er to the [datab
2f230 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2f240 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74  (the 1st paramet
2f250 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
2f260 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2f270 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
2f280 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2f290 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
2f2a0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
2f2b0 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
2f2c0 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
2f2d0 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
2f2e0 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74  nction..*/.sqlit
2f2f0 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74  e3 *sqlite3_cont
2f300 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  ext_db_handle(sq
2f310 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
2f320 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f330 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c  : Function Auxil
2f340 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20  iary Data.**.** 
2f350 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77  The following tw
2f360 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  o functions may 
2f370 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61  be used by scala
2f380 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  r SQL functions 
2f390 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20  to.** associate 
2f3a0 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72  metadata with ar
2f3b0 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49  gument values. I
2f3c0 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  f the same value
2f3d0 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a   is passed to.**
2f3e0 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61   multiple invoca
2f3f0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
2f400 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64  e SQL function d
2f410 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63  uring query exec
2f420 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20  ution, under.** 
2f430 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63  some circumstanc
2f440 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65  es the associate
2f450 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62  d metadata may b
2f460 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69  e preserved. Thi
2f470 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64  s may.** be used
2f480 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74  , for example, t
2f490 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d  o add a regular-
2f4a0 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68  expression match
2f4b0 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75  ing scalar.** fu
2f4c0 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70  nction. The comp
2f4d0 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20  iled version of 
2f4e0 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
2f4f0 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64  ession is stored
2f500 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20   as.** metadata 
2f510 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2f520 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61  the SQL value pa
2f530 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75  ssed as the regu
2f540 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a  lar expression.*
2f550 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20  * pattern.  The 
2f560 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72  compiled regular
2f570 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
2f580 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c  be reused on mul
2f590 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  tiple.** invocat
2f5a0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
2f5b0 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61   function so tha
2f5c0 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70  t the original p
2f5d0 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a  attern string.**
2f5e0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
2f5f0 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20  o be recompiled 
2f600 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69  on each invocati
2f610 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
2f620 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
2f630 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
2f640 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2f650 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61   to the metadata
2f660 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62  .** associated b
2f670 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  y the sqlite3_se
2f680 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63  t_auxdata() func
2f690 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74  tion with the Nt
2f6a0 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61  h argument.** va
2f6b0 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69  lue to the appli
2f6c0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2f6d0 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20  unction. ^If no 
2f6e0 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65  metadata has bee
2f6f0 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73  n ever.** been s
2f700 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61  et for the Nth a
2f710 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66  rgument of the f
2f720 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74  unction, or if t
2f730 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
2f740 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  .** function par
2f750 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e 67  ameter has chang
2f760 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74  ed since the met
2f770 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a  a-data was set,.
2f780 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ** then sqlite3_
2f790 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 65  get_auxdata() re
2f7a0 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
2f7b0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
2f7c0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
2f7d0 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
2f7e0 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 64   saves the metad
2f7f0 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  ata.** pointed t
2f800 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72  o by its 3rd par
2f810 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65  ameter as the me
2f820 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e  tadata for the N
2f830 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  -th.** argument 
2f840 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
2f850 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2f860 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ion.  Subsequent
2f870 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
2f880 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2f890 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20  () might return 
2f8a0 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74  this data, if it
2f8b0 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e   has.** not been
2f8c0 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e   destroyed..** ^
2f8d0 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c  If it is not NUL
2f8e0 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69  L, SQLite will i
2f8f0 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75  nvoke the destru
2f900 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ctor.** function
2f910 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34 74   given by the 4t
2f920 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2f930 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2f940 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d  ta() on.** the m
2f950 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68 65  etadata when the
2f960 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66   corresponding f
2f970 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
2f980 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20  r changes.** or 
2f990 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61  when the SQL sta
2f9a0 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73  tement completes
2f9b0 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65  , whichever come
2f9c0 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53  s first..**.** S
2f9d0 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f  QLite is free to
2f9e0 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75   call the destru
2f9f0 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65  ctor and drop me
2fa00 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a  tadata on any.**
2fa10 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e   parameter of an
2fa20 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e  y function at an
2fa30 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f 6e  y time.  ^The on
2fa40 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73 20  ly guarantee is 
2fa50 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74  that.** the dest
2fa60 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63  ructor will be c
2fa70 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65  alled before the
2fa80 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72 6f   metadata is dro
2fa90 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  pped..**.** ^(In
2faa0 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64   practice, metad
2fab0 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64  ata is preserved
2fac0 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f   between functio
2fad0 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65  n calls for.** e
2fae0 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20  xpressions that 
2faf0 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20  are constant at 
2fb00 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68  compile time. Th
2fb10 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65  is includes lite
2fb20 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e  ral.** values an
2fb30 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e 29  d [parameters].)
2fb40 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ^.**.** These ro
2fb50 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
2fb60 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
2fb70 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
2fb80 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66  ich.** the SQL f
2fb90 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
2fba0 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
2fbb0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2fbc0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2fbd0 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20  *, int N);.void 
2fbe0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2fbf0 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
2fc00 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69  ext*, int N, voi
2fc10 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69  d*, void (*)(voi
2fc20 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*));.../*.** CA
2fc30 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74  PI3REF: Constant
2fc40 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69  s Defining Speci
2fc50 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65  al Destructor Be
2fc60 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65  havior.**.** The
2fc70 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76  se are special v
2fc80 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65  alues for the de
2fc90 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73  structor that is
2fca0 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
2fcb0 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d  e.** final argum
2fcc0 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  ent to routines 
2fcd0 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  like [sqlite3_re
2fce0 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e  sult_blob()].  ^
2fcf0 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  If the destructo
2fd00 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
2fd10 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
2fd20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
2fd30 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65  e content pointe
2fd40 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a  r is constant.**
2fd50 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20   and will never 
2fd60 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73  change.  It does
2fd70 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
2fd80 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65  destroyed.  ^The
2fd90 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  .** SQLITE_TRANS
2fda0 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73  IENT value means
2fdb0 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
2fdc0 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68  t will likely ch
2fdd0 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e  ange in.** the n
2fde0 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74  ear future and t
2fdf0 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c  hat SQLite shoul
2fe00 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70  d make its own p
2fe10 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a  rivate copy of.*
2fe20 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65  * the content be
2fe30 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a  fore returning..
2fe40 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65  **.** The typede
2fe50 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74  f is necessary t
2fe60 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72  o work around pr
2fe70 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69  oblems in certai
2fe80 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65  n.** C++ compile
2fe90 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20  rs.  See ticket 
2fea0 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65  #2191..*/.typede
2feb0 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
2fec0 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
2fed0 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e  )(void*);.#defin
2fee0 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20  e SQLITE_STATIC 
2fef0 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64       ((sqlite3_d
2ff00 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30  estructor_type)0
2ff10 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
2ff20 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73  _TRANSIENT   ((s
2ff30 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
2ff40 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a  r_type)-1)../*.*
2ff50 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74  * CAPI3REF: Sett
2ff60 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f  ing The Result O
2ff70 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f  f An SQL Functio
2ff80 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  n.**.** These ro
2ff90 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
2ffa0 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20  by the xFunc or 
2ffb0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73  xFinal callbacks
2ffc0 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65   that.** impleme
2ffd0 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  nt SQL functions
2ffe0 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
2fff0 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    See.** [sqlite
30000 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
30010 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
30020 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
30030 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64  n16()].** for ad
30040 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
30050 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion..**.** Thes
30060 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b  e functions work
30070 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20   very much like 
30080 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62  the [parameter b
30090 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f  inding] family o
300a0 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75  f.** functions u
300b0 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75  sed to bind valu
300c0 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d  es to host param
300d0 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65  eters in prepare
300e0 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  d statements..**
300f0 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53   Refer to the [S
30100 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f  QL parameter] do
30110 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
30120 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
30130 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  mation..**.** ^T
30140 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
30150 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  t_blob() interfa
30160 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
30170 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
30180 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
30190 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
301a0 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20   the BLOB whose 
301b0 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74  content is point
301c0 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20  ed.** to by the 
301d0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
301e0 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20   and which is N 
301f0 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65  bytes long where
30200 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69   N is the.** thi
30210 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
30220 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30230 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
30240 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65  () interfaces se
30250 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  t the result of.
30260 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
30270 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
30280 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42  ion to be a BLOB
30290 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20   containing all 
302a0 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e  zero.** bytes an
302b0 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  d N bytes in siz
302c0 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  e, where N is th
302d0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32  e value of the 2
302e0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  nd parameter..**
302f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30300 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29  _result_double()
30310 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
30320 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
30330 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
30340 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
30350 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74  on to be a float
30360 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20  ing point value 
30370 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
30380 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  its 2nd argument
30390 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
303a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
303b0 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
303c0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
303d0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61   functions.** ca
303e0 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  use the implemen
303f0 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ted SQL function
30400 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63   to throw an exc
30410 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69  eption..** ^SQLi
30420 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69  te uses the stri
30430 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ng pointed to by
30440 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61   the.** 2nd para
30450 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
30460 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
30470 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
30480 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61  t_error16().** a
30490 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e  s the text of an
304a0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20   error message. 
304b0 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72   ^SQLite interpr
304c0 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a  ets the error.**
304d0 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
304e0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
304f0 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55  ult_error() as U
30500 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a  TF-8. ^SQLite.**
30510 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
30520 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
30530 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
30540 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69  16() as UTF-16 i
30550 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65  n native.** byte
30560 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65   order.  ^If the
30570 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
30580 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
30590 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
305a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
305b0 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67  error16() is neg
305c0 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
305d0 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65  e takes as the e
305e0 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
305f0 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f  all text up thro
30600 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
30610 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
30620 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
30630 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
30640 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
30650 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
30660 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
30670 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  ) is non-negativ
30680 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
30690 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a  kes that many.**
306a0 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
306b0 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65  acters) from the
306c0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
306d0 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  s the error mess
306e0 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  age..** ^The sql
306f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
30700 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
30710 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
30720 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b  .** routines mak
30730 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79  e a private copy
30740 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65   of the error me
30750 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72  ssage text befor
30760 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e  e.** they return
30770 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61  .  Hence, the ca
30780 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  lling function c
30790 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72  an deallocate or
307a0 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74  .** modify the t
307b0 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72  ext after they r
307c0 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61  eturn without ha
307d0 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  rm..** ^The sqli
307e0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
307f0 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e  _code() function
30800 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72   changes the err
30810 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72  or code.** retur
30820 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73  ned by SQLite as
30830 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20   a result of an 
30840 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74  error in a funct
30850 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c  ion.  ^By defaul
30860 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20  t,.** the error 
30870 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45  code is SQLITE_E
30880 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71  RROR.  ^A subseq
30890 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
308a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
308b0 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
308c0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
308d0 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72  () resets the er
308e0 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49  ror code to SQLI
308f0 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20  TE_ERROR..**.** 
30900 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
30910 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74  ult_toobig() int
30920 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
30930 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
30940 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61   error.** indica
30950 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69  ting that a stri
30960 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f  ng or BLOB is to
30970 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73  o long to repres
30980 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
30990 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
309a0 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65  omem() interface
309b0 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
309c0 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72  o throw an error
309d0 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74  .** indicating t
309e0 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  hat a memory all
309f0 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a  ocation failed..
30a00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
30a10 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20  e3_result_int() 
30a20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
30a30 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
30a40 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
30a50 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
30a60 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
30a70 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69   32-bit signed i
30a80 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
30a90 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
30aa0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
30ab0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
30ac0 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66  t_int64() interf
30ad0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
30ae0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
30af0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
30b00 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
30b10 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69   to be the 64-bi
30b20 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
30b30 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
30b40 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
30b50 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
30b60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
30b70 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20  ull() interface 
30b80 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
30b90 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
30ba0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
30bb0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
30bc0 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  be NULL..**.** ^
30bd0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
30be0 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74  lt_text(), sqlit
30bf0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
30c00 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  (),.** sqlite3_r
30c10 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29  esult_text16le()
30c20 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  , and sqlite3_re
30c30 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20  sult_text16be() 
30c40 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65  interfaces.** se
30c50 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  t the return val
30c60 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ue of the applic
30c70 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
30c80 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  nction to be.** 
30c90 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68  a text string wh
30ca0 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74  ich is represent
30cb0 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46  ed as UTF-8, UTF
30cc0 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
30cd0 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36  order,.** UTF-16
30ce0 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20   little endian, 
30cf0 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e  or UTF-16 big en
30d00 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65  dian, respective
30d10 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74  ly..** ^SQLite t
30d20 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65  akes the text re
30d30 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70  sult from the ap
30d40 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a  plication from.*
30d50 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  * the 2nd parame
30d60 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ter of the sqlit
30d70 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
30d80 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e  interfaces..** ^
30d90 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
30da0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
30db0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
30dc0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
30dd0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
30de0 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65   SQLite takes re
30df0 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74  sult text from t
30e00 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
30e10 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20  .** through the 
30e20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
30e30 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  cter..** ^If the
30e40 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
30e50 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
30e60 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
30e70 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d  faces.** is non-
30e80 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61  negative, then a
30e90 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f  s many bytes (no
30ea0 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66  t characters) of
30eb0 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69   the text.** poi
30ec0 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32  nted to by the 2
30ed0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65  nd parameter are
30ee0 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70   taken as the ap
30ef0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
30f00 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65  d.** function re
30f10 73 75 6c 74 2e 20 20 49 66 20 74 68 65 20 33 72  sult.  If the 3r
30f20 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  d parameter is n
30f30 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
30f40 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62 65 20  n it.** must be 
30f50 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 20  the byte offset 
30f60 69 6e 74 6f 20 74 68 65 20 73 74 72 69 6e 67 20  into the string 
30f70 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65  where the NUL te
30f80 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 0a 2a  rminator would.*
30f90 2a 20 61 70 70 65 61 72 20 69 66 20 74 68 65 20  * appear if the 
30fa0 73 74 72 69 6e 67 20 77 68 65 72 65 20 4e 55 4c  string where NUL
30fb0 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66   terminated.  If
30fc0 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74   any NUL charact
30fd0 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ers occur.** in 
30fe0 74 68 65 20 73 74 72 69 6e 67 20 61 74 20 61 20  the string at a 
30ff0 62 79 74 65 20 6f 66 66 73 65 74 20 74 68 61 74  byte offset that
31000 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 74 68   is less than th
31010 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 33  e value of the 3
31020 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c  rd.** parameter,
31030 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
31040 69 6e 67 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  ing string will 
31050 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64  contain embedded
31060 20 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a 2a 2a   NULs and the.**
31070 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65   result of expre
31080 73 73 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67  ssions operating
31090 20 6f 6e 20 73 74 72 69 6e 67 73 20 77 69 74 68   on strings with
310a0 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69   embedded NULs i
310b0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
310c0 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
310d0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
310e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
310f0 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
31100 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
31110 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d  t_blob is a non-
31120 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
31130 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20  en SQLite calls 
31140 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  that.** function
31150 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74   as the destruct
31160 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f  or on the text o
31170 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68  r BLOB result wh
31180 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e  en it has.** fin
31190 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74  ished using that
311a0 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20   result..** ^If 
311b0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
311c0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
311d0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
311e0 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a  terfaces or to.*
311f0 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
31200 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65  _blob is the spe
31210 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51  cial constant SQ
31220 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65  LITE_STATIC, the
31230 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75  n SQLite.** assu
31240 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78  mes that the tex
31250 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74  t or BLOB result
31260 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20   is in constant 
31270 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
31280 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63  ot.** copy the c
31290 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61  ontent of the pa
312a0 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c  rameter nor call
312b0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e   a destructor on
312c0 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20   the content.** 
312d0 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69  when it has fini
312e0 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
312f0 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74  result..** ^If t
31300 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
31310 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
31320 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
31330 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71  erfaces.** or sq
31340 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
31350 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
31360 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
31370 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68  _TRANSIENT.** th
31380 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  en SQLite makes 
31390 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65  a copy of the re
313a0 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20  sult into space 
313b0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a  obtained from.**
313c0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
313d0 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20  alloc()] before 
313e0 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  it returns..**.*
313f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
31400 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
31410 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
31420 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68   result of.** th
31430 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
31440 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
31450 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a  o be a copy the.
31460 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
31470 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
31480 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20  bject specified 
31490 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
314a0 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  eter.  ^The.** s
314b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
314c0 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
314d0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
314e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
314f0 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74  ue].** so that t
31500 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
31510 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20  e] specified in 
31520 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  the parameter ma
31530 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62  y change or.** b
31540 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66  e deallocated af
31550 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75  ter sqlite3_resu
31560 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72  lt_value() retur
31570 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e  ns without harm.
31580 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65  .** ^A [protecte
31590 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
315a0 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61   object may alwa
315b0 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65  ys be used where
315c0 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
315d0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
315e0 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71  e] object is req
315f0 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72  uired, so either
31600 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c  .** kind of [sql
31610 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
31620 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77  ct can be used w
31630 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61  ith this interfa
31640 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ce..**.** If the
31650 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
31660 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68  called from with
31670 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74  in the different
31680 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20   thread.** than 
31690 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69  the one containi
316a0 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ng the applicati
316b0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
316c0 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65  ion that receive
316d0 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  d.** the [sqlite
316e0 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74  3_context] point
316f0 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  er, the results 
31700 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
31710 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
31720 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74  esult_blob(sqlit
31730 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
31740 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
31750 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
31760 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
31770 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ult_double(sqlit
31780 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75  e3_context*, dou
31790 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ble);.void sqlit
317a0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
317b0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
317c0 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
317d0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
317e0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
317f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
31800 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
31810 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
31820 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
31830 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63  toobig(sqlite3_c
31840 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
31850 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
31860 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65  ror_nomem(sqlite
31870 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
31880 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
31890 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69  _error_code(sqli
318a0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
318b0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
318c0 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69  _result_int(sqli
318d0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
318e0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
318f0 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71  _result_int64(sq
31900 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
31910 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
31920 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
31930 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ult_null(sqlite3
31940 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
31950 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31960 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
31970 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
31980 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  r*, int, void(*)
31990 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
319a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
319b0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  xt16(sqlite3_con
319c0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
319d0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
319e0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
319f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
31a00 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63  xt16le(sqlite3_c
31a10 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
31a20 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
31a30 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
31a40 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
31a50 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
31a60 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
31a70 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
31a80 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
31a90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31aa0 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f  value(sqlite3_co
31ab0 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
31ac0 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71  value*);.void sq
31ad0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
31ae0 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  oblob(sqlite3_co
31af0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a  ntext*, int n);.
31b00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31b10 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c   Define New Coll
31b20 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a  ating Sequences.
31b30 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  **.** ^These fun
31b40 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f  ctions add, remo
31b50 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61 20  ve, or modify a 
31b60 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f  [collation] asso
31b70 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74  ciated.** with t
31b80 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
31b90 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
31ba0 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
31bb0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
31bc0 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
31bd0 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20   collation is a 
31be0 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
31bf0 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
31c00 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61  te_collation() a
31c10 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nd sqlite3_creat
31c20 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
31c30 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36  .** and a UTF-16
31c40 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76   string in nativ
31c50 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72  e byte order for
31c60 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
31c70 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a  collation16()..*
31c80 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d  * ^Collation nam
31c90 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65 20  es that compare 
31ca0 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67 20  equal according 
31cb0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e  to [sqlite3_strn
31cc0 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63  icmp()] are.** c
31cd0 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 20  onsidered to be 
31ce0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a  the same name..*
31cf0 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 72 64  *.** ^(The third
31d00 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65 78 74   argument (eText
31d10 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f 6e 65  Rep) must be one
31d20 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74   of the constant
31d30 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  s:.** <ul>.** <l
31d40 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  i> [SQLITE_UTF8]
31d50 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
31d60 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c  E_UTF16LE],.** <
31d70 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
31d80 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  6BE],.** <li> [S
31d90 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72  QLITE_UTF16], or
31da0 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
31db0 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e  _UTF16_ALIGNED].
31dc0 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e  .** </ul>)^.** ^
31dd0 54 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67  The eTextRep arg
31de0 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e 65 73  ument determines
31df0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66   the encoding of
31e00 20 73 74 72 69 6e 67 73 20 70 61 73 73 65 64 0a   strings passed.
31e10 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  ** to the collat
31e20 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  ing function cal
31e30 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b  lback, xCallback
31e40 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
31e50 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b 53 51  E_UTF16] and [SQ
31e60 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
31e70 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 20 65  ED] values for e
31e80 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65  TextRep.** force
31e90 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20 55   strings to be U
31ea0 54 46 31 36 20 77 69 74 68 20 6e 61 74 69 76 65  TF16 with native
31eb0 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20   byte order..** 
31ec0 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46  ^The [SQLITE_UTF
31ed0 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75  16_ALIGNED] valu
31ee0 65 20 66 6f 72 20 65 54 65 78 74 52 65 70 20 66  e for eTextRep f
31ef0 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20 74 6f  orces strings to
31f00 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20   begin.** on an 
31f10 65 76 65 6e 20 62 79 74 65 20 61 64 64 72 65 73  even byte addres
31f20 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  s..**.** ^The fo
31f30 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 70  urth argument, p
31f40 41 72 67 2c 20 69 73 20 61 6e 20 61 70 70 6c 69  Arg, is an appli
31f50 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
31f60 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73 73  ter that is pass
31f70 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 73  ed.** through as
31f80 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
31f90 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  ent to the colla
31fa0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ting function ca
31fb0 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54  llback..**.** ^T
31fc0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
31fd0 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73  t, xCallback, is
31fe0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
31ff0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
32000 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70  tion..** ^Multip
32010 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  le collating fun
32020 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72 65  ctions can be re
32030 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74  gistered using t
32040 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74  he same name but
32050 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72 65  .** with differe
32060 6e 74 20 65 54 65 78 74 52 65 70 20 70 61 72 61  nt eTextRep para
32070 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69 74  meters and SQLit
32080 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63 68  e will use which
32090 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ever.** function
320a0 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c 65   requires the le
320b0 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
320c0 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f  ta transformatio
320d0 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78 43  n..** ^If the xC
320e0 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74  allback argument
320f0 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68   is NULL then th
32100 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
32110 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74  tion is.** delet
32120 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63  ed.  ^When all c
32130 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
32140 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20 73 61  ns having the sa
32150 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c 65  me name are dele
32160 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c  ted,.** that col
32170 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e  lation is no lon
32180 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a  ger usable..**.*
32190 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67  * ^The collating
321a0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
321b0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
321c0 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  th a copy of the
321d0 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63   pArg .** applic
321e0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
321f0 65 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f 20  er and with two 
32200 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 65  strings in the e
32210 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65  ncoding specifie
32220 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65 78  d.** by the eTex
32230 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20 20  tRep argument.  
32240 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  The collating fu
32250 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 75  nction must retu
32260 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72  rn an.** integer
32270 20 74 68 61 74 20 69 73 20 6e 65 67 61 74 69 76   that is negativ
32280 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69  e, zero, or posi
32290 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20 66  tive.** if the f
322a0 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c  irst string is l
322b0 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20  ess than, equal 
322c0 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74  to, or greater t
322d0 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a  han the second,.
322e0 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
322f0 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75    A collating fu
32300 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61  nction must alwa
32310 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 61  ys return the sa
32320 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76  me answer.** giv
32330 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75  en the same inpu
32340 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 6d  ts.  If two or m
32350 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  ore collating fu
32360 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67 69  nctions are regi
32370 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65  stered.** to the
32380 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20   same collation 
32390 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66 66  name (using diff
323a0 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 76  erent eTextRep v
323b0 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a  alues) then all.
323c0 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e 20  ** must give an 
323d0 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 65  equivalent answe
323e0 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77  r when invoked w
323f0 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20 73  ith equivalent s
32400 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63  trings..** The c
32410 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
32420 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65 20  n must obey the 
32430 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72  following proper
32440 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20  ties for all.** 
32450 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e  strings A, B, an
32460 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  d C:.**.** <ol>.
32470 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20  ** <li> If A==B 
32480 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c  then B==A..** <l
32490 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 42  i> If A==B and B
324a0 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a  ==C then A==C..*
324b0 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42  * <li> If A&lt;B
324c0 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a   THEN B&gt;A..**
324d0 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20   <li> If A&lt;B 
324e0 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e 20  and B&lt;C then 
324f0 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  A&lt;C..** </ol>
32500 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c  .**.** If a coll
32510 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66  ating function f
32520 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 20  ails any of the 
32530 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e 74  above constraint
32540 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f  s and that.** co
32550 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
32560 20 69 73 20 20 72 65 67 69 73 74 65 72 65 64 20   is  registered 
32570 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20 74  and used, then t
32580 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  he behavior of S
32590 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65  QLite.** is unde
325a0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
325b0 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
325c0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
325d0 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
325e0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
325f0 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 68  ion().** with th
32600 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20  e addition that 
32610 74 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c  the xDestroy cal
32620 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
32630 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a   on pArg when.**
32640 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
32650 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74  unction is delet
32660 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e  ed..** ^Collatin
32670 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  g functions are 
32680 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65  deleted when the
32690 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e  y are overridden
326a0 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c   by later.** cal
326b0 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  ls to the collat
326c0 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e  ion creation fun
326d0 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74  ctions or when t
326e0 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
326f0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63  connection] is c
32700 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  losed using [sql
32710 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a  ite3_close()]..*
32720 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 72  *.** ^The xDestr
32730 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c  oy callback is <
32740 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64  u>not</u> called
32750 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69   if the .** sqli
32760 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
32770 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 69  tion_v2() functi
32780 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c 69  on fails.  Appli
32790 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e 76  cations that inv
327a0 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  oke.** sqlite3_c
327b0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
327c0 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d  v2() with a non-
327d0 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 72  NULL xDestroy ar
327e0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a  gument should .*
327f0 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  * check the retu
32800 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73 70  rn code and disp
32810 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69  ose of the appli
32820 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
32830 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65  ter.** themselve
32840 73 20 72 61 74 68 65 72 20 74 68 61 6e 20 65 78  s rather than ex
32850 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20 74  pecting SQLite t
32860 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74 20 66  o deal with it f
32870 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73  or them..** This
32880 20 69 73 20 64 69 66 66 65 72 65 6e 74 20 66 72   is different fr
32890 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20 53  om every other S
328a0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
328b0 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 65    The inconsiste
328c0 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72  ncy .** is unfor
328d0 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e 6e 6f  tunate but canno
328e0 74 20 62 65 20 63 68 61 6e 67 65 64 20 77 69 74  t be changed wit
328f0 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 62 61  hout breaking ba
32900 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70  ckwards .** comp
32910 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
32920 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c   See also:  [sql
32930 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
32940 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71  eeded()] and [sq
32950 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
32960 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a  needed16()]..*/.
32970 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
32980 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20  te_collation(.  
32990 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
329a0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
329b0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
329c0 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a   .  void *pArg,.
329d0 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
329e0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
329f0 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
32a00 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73   void*).);.int s
32a10 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
32a20 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  llation_v2(.  sq
32a30 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
32a40 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
32a50 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
32a60 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20    void *pArg,.  
32a70 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
32a80 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
32a90 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
32aa0 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  oid*),.  void(*x
32ab0 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
32ac0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
32ad0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
32ae0 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
32af0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e    const void *zN
32b00 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  ame,.  int eText
32b10 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41  Rep, .  void *pA
32b20 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  rg,.  int(*xComp
32b30 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
32b40 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
32b50 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
32b60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32b70 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64  Collation Needed
32b80 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
32b90 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e   ^To avoid havin
32ba0 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c  g to register al
32bb0 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  l collation sequ
32bc0 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64  ences before a d
32bd0 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62  atabase.** can b
32be0 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65  e used, a single
32bf0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
32c00 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74  on may be regist
32c10 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  ered with the.**
32c20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
32c30 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76  ction] to be inv
32c40 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e  oked whenever an
32c50 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
32c60 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
32c70 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a   is required..**
32c80 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63  .** ^If the func
32c90 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72  tion is register
32ca0 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  ed using the sql
32cb0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
32cc0 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20  eeded() API,.** 
32cd0 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65  then it is passe
32ce0 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75  d the names of u
32cf0 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
32d00 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20  on sequences as 
32d10 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64  strings.** encod
32d20 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66  ed in UTF-8. ^If
32d30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
32d40 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73  on_needed16() is
32d50 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61   used,.** the na
32d60 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61  mes are passed a
32d70 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68  s UTF-16 in mach
32d80 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  ine native byte 
32d90 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c  order..** ^A cal
32da0 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63  l to either func
32db0 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68  tion replaces th
32dc0 65 20 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61  e existing colla
32dd0 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c  tion-needed call
32de0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68  back..**.** ^(Wh
32df0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
32e00 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20  is invoked, the 
32e10 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70  first argument p
32e20 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a  assed is a copy.
32e30 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ** of the second
32e40 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
32e50 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
32e60 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71  eeded() or.** sq
32e70 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
32e80 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65  needed16().  The
32e90 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
32ea0 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
32eb0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
32ec0 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
32ed0 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  ent is one of [S
32ee0 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51  QLITE_UTF8], [SQ
32ef0 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a  LITE_UTF16BE],.*
32f00 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  * or [SQLITE_UTF
32f10 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e  16LE], indicatin
32f20 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72  g the most desir
32f30 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65  able form of the
32f40 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
32f50 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20  quence function 
32f60 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 66  required.  The f
32f70 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
32f80 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
32f90 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63  he.** required c
32fa0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
32fb0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  e.)^.**.** The c
32fc0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
32fd0 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72   should register
32fe0 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c   the desired col
32ff0 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  lation using.** 
33000 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
33010 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73  collation()], [s
33020 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
33030 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72  llation16()], or
33040 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
33050 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
33060 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
33070 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
33080 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a  eded(.  sqlite3*
33090 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76  , .  void*, .  v
330a0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
330b0 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
330c0 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a  ep,const char*).
330d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
330e0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
330f0 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
33100 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28    void*,.  void(
33110 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
33120 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
33130 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
33140 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41  #ifdef SQLITE_HA
33150 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70  S_CODEC./*.** Sp
33160 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f  ecify the key fo
33170 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64  r an encrypted d
33180 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72  atabase.  This r
33190 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65  outine should be
331a0 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74  .** called right
331b0 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f   after sqlite3_o
331c0 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  pen()..**.** The
331d0 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
331e0 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
331f0 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
33200 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
33210 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
33220 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
33230 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
33240 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
33250 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
33260 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
33270 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
33280 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
33290 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a      /* The key *
332a0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e  /.);../*.** Chan
332b0 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e  ge the key on an
332c0 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20   open database. 
332d0 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   If the current 
332e0 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a  database is not.
332f0 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68  ** encrypted, th
33300 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
33310 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20  encrypt it.  If 
33320 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d  pNew==0 or nNew=
33330 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  =0, the.** datab
33340 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64  ase is decrypted
33350 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
33360 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
33370 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
33380 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
33390 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
333a0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
333b0 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79  nt sqlite3_rekey
333c0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
333d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
333e0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
333f0 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
33400 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
33410 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
33420 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20   /* The new key 
33430 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65  */.);../*.** Spe
33440 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74  cify the activat
33450 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45  ion key for a SE
33460 45 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c  E database.  Unl
33470 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65  ess .** activate
33480 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53  d, none of the S
33490 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c  EE routines will
334a0 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73   work..*/.void s
334b0 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f  qlite3_activate_
334c0 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  see(.  const cha
334d0 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20  r *zPassPhrase  
334e0 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74        /* Activat
334f0 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b  ion phrase */.);
33500 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20  .#endif..#ifdef 
33510 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45  SQLITE_ENABLE_CE
33520 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  ROD./*.** Specif
33530 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e  y the activation
33540 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44   key for a CEROD
33550 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65   database.  Unle
33560 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64  ss .** activated
33570 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45  , none of the CE
33580 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c  ROD routines wil
33590 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20  l work..*/.void 
335a0 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65  sqlite3_activate
335b0 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20  _cerod(.  const 
335c0 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73  char *zPassPhras
335d0 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69  e        /* Acti
335e0 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f  vation phrase */
335f0 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  .);.#endif../*.*
33600 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70  * CAPI3REF: Susp
33610 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f  end Execution Fo
33620 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a  r A Short Time.*
33630 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
33640 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f  _sleep() functio
33650 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72  n causes the cur
33660 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73  rent thread to s
33670 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e  uspend execution
33680 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74  .** for at least
33690 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c   a number of mil
336a0 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66  liseconds specif
336b0 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d  ied in its param
336c0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  eter..**.** If t
336d0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
336e0 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70  tem does not sup
336f0 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65  port sleep reque
33700 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c  sts with.** mill
33710 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73  isecond time res
33720 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  olution, then th
33730 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72  e time will be r
33740 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20  ounded up to.** 
33750 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f  the nearest seco
33760 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f  nd. The number o
33770 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  f milliseconds o
33780 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79  f sleep actually
33790 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72  .** requested fr
337a0 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  om the operating
337b0 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72   system is retur
337c0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ned..**.** ^SQLi
337d0 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  te implements th
337e0 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20  is interface by 
337f0 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65  calling the xSle
33800 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f  ep().** method o
33810 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
33820 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
33830 63 74 2e 20 20 49 66 20 74 68 65 20 78 53 6c 65  ct.  If the xSle
33840 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  ep() method.** o
33850 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  f the default VF
33860 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  S is not impleme
33870 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79 2c 20  nted correctly, 
33880 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74  or not implement
33890 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68  ed at.** all, th
338a0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
338b0 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  of sqlite3_sleep
338c0 28 29 20 6d 61 79 20 64 65 76 69 61 74 65 20 66  () may deviate f
338d0 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69 70 74  rom the descript
338e0 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72  ion.** in the pr
338f0 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68  evious paragraph
33900 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
33910 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f  3_sleep(int);../
33920 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
33930 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65  ame Of The Folde
33940 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72  r Holding Tempor
33950 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20  ary Files.**.** 
33960 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c  ^(If this global
33970 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64   variable is mad
33980 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20  e to point to a 
33990 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a  string which is.
339a0 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61  ** the name of a
339b0 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20   folder (a.k.a. 
339c0 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e  directory), then
339d0 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66   all temporary f
339e0 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20  iles.** created 
339f0 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75  by SQLite when u
33a00 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20  sing a built-in 
33a10 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56  [sqlite3_vfs | V
33a20 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70  FS].** will be p
33a30 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69  laced in that di
33a40 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20  rectory.)^  ^If 
33a50 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a  this variable.**
33a60 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
33a70 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
33a80 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63  performs a searc
33a90 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72  h for an appropr
33aa0 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  iate.** temporar
33ab0 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79  y file directory
33ac0 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ..**.** It is no
33ad0 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f  t safe to read o
33ae0 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  r modify this va
33af0 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74  riable in more t
33b00 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61  han one.** threa
33b10 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74  d at a time.  It
33b20 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
33b30 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
33b40 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  his variable.** 
33b50 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  if a [database c
33b60 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
33b70 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20  ing used at the 
33b80 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73  same time in a s
33b90 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61  eparate.** threa
33ba0 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65  d..** It is inte
33bb0 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76  nded that this v
33bc0 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f  ariable be set o
33bd0 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f  nce.** as part o
33be0 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  f process initia
33bf0 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66  lization and bef
33c00 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  ore any SQLite i
33c10 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74  nterface.** rout
33c20 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63  ines have been c
33c30 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74  alled and that t
33c40 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d  his variable rem
33c50 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a  ain unchanged.**
33c60 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a   thereafter..**.
33c70 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74  ** ^The [temp_st
33c80 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
33c90 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79  agma] may modify
33ca0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61   this variable a
33cb0 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74  nd cause.** it t
33cc0 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
33cd0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
33ce0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
33cf0 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c  .  ^Furthermore,
33d00 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74  .** the [temp_st
33d10 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
33d20 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73  agma] always ass
33d30 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74  umes that any st
33d40 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69  ring.** that thi
33d50 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74  s variable point
33d60 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20  s to is held in 
33d70 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
33d80 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
33d90 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68  3_malloc] and th
33da0 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74  e pragma may att
33db0 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61  empt to free tha
33dc0 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e  t memory.** usin
33dd0 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d  g [sqlite3_free]
33de0 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74  ..** Hence, if t
33df0 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20  his variable is 
33e00 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c  modified directl
33e10 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f  y, either it sho
33e20 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e  uld be.** made N
33e30 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70  ULL or made to p
33e40 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f  oint to memory o
33e50 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
33e60 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a  lite3_malloc].**
33e70 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65   or else the use
33e80 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74   of the [temp_st
33e90 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
33ea0 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20  agma] should be 
33eb0 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49  avoided..*/.SQLI
33ec0 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a  TE_EXTERN char *
33ed0 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72  sqlite3_temp_dir
33ee0 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ectory;../*.** C
33ef0 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f  API3REF: Test Fo
33f00 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f  r Auto-Commit Mo
33f10 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  de.** KEYWORDS: 
33f20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  {autocommit mode
33f30 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  }.**.** ^The sql
33f40 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d  ite3_get_autocom
33f50 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  mit() interface 
33f60 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
33f70 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74   or.** zero if t
33f80 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 73  he given databas
33f90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
33fa0 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74  or is not in aut
33fb0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a  ocommit mode,.**
33fc0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20   respectively.  
33fd0 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  ^Autocommit mode
33fe0 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c   is on by defaul
33ff0 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69  t..** ^Autocommi
34000 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c  t mode is disabl
34010 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20  ed by a [BEGIN] 
34020 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41  statement..** ^A
34030 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
34040 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20  s re-enabled by 
34050 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52  a [COMMIT] or [R
34060 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  OLLBACK]..**.** 
34070 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73  If certain kinds
34080 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72   of errors occur
34090 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20   on a statement 
340a0 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73  within a multi-s
340b0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e  tatement.** tran
340c0 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20  saction (errors 
340d0 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54  including [SQLIT
340e0 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45  E_FULL], [SQLITE
340f0 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  _IOERR],.** [SQL
34100 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c  ITE_NOMEM], [SQL
34110 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b  ITE_BUSY], and [
34120 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
34130 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74  ]) then the.** t
34140 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74  ransaction might
34150 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
34160 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
34170 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a  The only way to.
34180 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74  ** find out whet
34190 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d  her SQLite autom
341a0 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
341b0 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
341c0 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e  tion after.** an
341d0 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65   error is to use
341e0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a   this function..
341f0 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72  **.** If another
34200 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20   thread changes 
34210 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73  the autocommit s
34220 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74  tatus of the dat
34230 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
34240 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72  ion while this r
34250 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e  outine is runnin
34260 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  g, then the retu
34270 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75  rn value.** is u
34280 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74  ndefined..*/.int
34290 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74   sqlite3_get_aut
342a0 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a  ocommit(sqlite3*
342b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
342c0 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74  EF: Find The Dat
342d0 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20  abase Handle Of 
342e0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
342f0 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ment.**.** ^The 
34300 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
34310 65 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  e interface retu
34320 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61 73  rns the [databas
34330 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
34340 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68  ndle.** to which
34350 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
34360 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e  tement] belongs.
34370 20 20 5e 54 68 65 20 5b 64 61 74 61 62 61 73 65    ^The [database
34380 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
34390 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
343a0 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73  te3_db_handle is
343b0 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
343c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
343d0 2a 2a 20 74 68 61 74 20 77 61 73 20 74 68 65 20  ** that was the 
343e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a  first argument.*
343f0 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
34400 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
34410 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72  call (or its var
34420 69 61 6e 74 73 29 20 74 68 61 74 20 77 61 73 20  iants) that was 
34430 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74  used to.** creat
34440 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  e the statement 
34450 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61  in the first pla
34460 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a  ce..*/.sqlite3 *
34470 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
34480 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  e(sqlite3_stmt*)
34490 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
344a0 46 3a 20 52 65 74 75 72 6e 20 54 68 65 20 46 69  F: Return The Fi
344b0 6c 65 6e 61 6d 65 20 46 6f 72 20 41 20 44 61 74  lename For A Dat
344c0 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
344d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
344e0 74 65 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28  te3_db_filename(
344f0 44 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72  D,N) interface r
34500 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
34510 20 74 6f 20 61 20 66 69 6c 65 6e 61 6d 65 0a 2a   to a filename.*
34520 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
34530 68 20 64 61 74 61 62 61 73 65 20 4e 20 6f 66 20  h database N of 
34540 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 5e  connection D.  ^
34550 54 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73  The main databas
34560 65 20 66 69 6c 65 0a 2a 2a 20 68 61 73 20 74 68  e file.** has th
34570 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 2e 20 20  e name "main".  
34580 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 61  If there is no a
34590 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
345a0 20 4e 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61   N on the databa
345b0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
345c0 20 44 2c 20 6f 72 20 69 66 20 64 61 74 61 62 61   D, or if databa
345d0 73 65 20 4e 20 69 73 20 61 20 74 65 6d 70 6f 72  se N is a tempor
345e0 61 72 79 20 6f 72 20 69 6e 2d 6d 65 6d 6f 72 79  ary or in-memory
345f0 20 64 61 74 61 62 61 73 65 2c 20 74 68 65 6e 0a   database, then.
34600 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
34610 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
34620 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 6c 65 6e 61  *.** ^The filena
34630 6d 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  me returned by t
34640 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
34650 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 74 68  the output of th
34660 65 0a 2a 2a 20 78 46 75 6c 6c 50 61 74 68 6e 61  e.** xFullPathna
34670 6d 65 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  me method of the
34680 20 5b 56 46 53 5d 2e 20 20 5e 49 6e 20 6f 74 68   [VFS].  ^In oth
34690 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 66 69  er words, the fi
346a0 6c 65 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 62  lename.** will b
346b0 65 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61  e an absolute pa
346c0 74 68 6e 61 6d 65 2c 20 65 76 65 6e 20 69 66 20  thname, even if 
346d0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 75 73 65  the filename use
346e0 64 0a 2a 2a 20 74 6f 20 6f 70 65 6e 20 74 68 65  d.** to open the
346f0 20 64 61 74 61 62 61 73 65 20 6f 72 69 67 69 6e   database origin
34700 61 6c 6c 79 20 77 61 73 20 61 20 55 52 49 20 6f  ally was a URI o
34710 72 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 6e  r relative pathn
34720 61 6d 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ame..*/.const ch
34730 61 72 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 66  ar *sqlite3_db_f
34740 69 6c 65 6e 61 6d 65 28 73 71 6c 69 74 65 33 20  ilename(sqlite3 
34750 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  *db, const char 
34760 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  *zDbName);../*.*
34770 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64  * CAPI3REF: Find
34780 20 74 68 65 20 6e 65 78 74 20 70 72 65 70 61 72   the next prepar
34790 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  ed statement.**.
347a0 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61  ** ^This interfa
347b0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
347c0 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74  nter to the next
347d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
347e0 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70  ment] after.** p
347f0 53 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20  Stmt associated 
34800 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
34810 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
34820 44 62 2e 20 20 5e 49 66 20 70 53 74 6d 74 20 69  Db.  ^If pStmt i
34830 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74  s NULL.** then t
34840 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65  his interface re
34850 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
34860 74 6f 20 74 68 65 20 66 69 72 73 74 20 70 72 65  to the first pre
34870 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
34880 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
34890 74 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20  th the database 
348a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20  connection pDb. 
348b0 20 5e 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64   ^If no prepared
348c0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61   statement.** sa
348d0 74 69 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64  tisfies the cond
348e0 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72  itions of this r
348f0 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72  outine, it retur
34900 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  ns NULL..**.** T
34910 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
34920 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72  nection] pointer
34930 20 44 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a   D in a call to.
34940 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74  ** [sqlite3_next
34950 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74  _stmt(D,S)] must
34960 20 72 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65   refer to an ope
34970 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  n database.** co
34980 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20  nnection and in 
34990 70 61 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20  particular must 
349a0 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  not be a NULL po
349b0 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65  inter..*/.sqlite
349c0 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f  3_stmt *sqlite3_
349d0 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65  next_stmt(sqlite
349e0 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f  3 *pDb, sqlite3_
349f0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
34a00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
34a10 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61  ommit And Rollba
34a20 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20  ck Notification 
34a30 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
34a40 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
34a50 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  mit_hook() inter
34a60 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
34a70 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
34a80 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f  ction to be invo
34a90 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74  ked whenever a t
34aa0 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 43  ransaction is [C
34ab0 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 74 74 65  OMMIT | committe
34ac0 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c  d]..** ^Any call
34ad0 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
34ae0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73  evious call to s
34af0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
34b00 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ok().** for the 
34b10 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
34b20 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72  nnection is over
34b30 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20  ridden..** ^The 
34b40 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
34b50 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63  _hook() interfac
34b60 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
34b70 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
34b80 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  on to be invoked
34b90 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e   whenever a tran
34ba0 73 61 63 74 69 6f 6e 20 69 73 20 5b 52 4f 4c 4c  saction is [ROLL
34bb0 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 62 61  BACK | rolled ba
34bc0 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c  ck]..** ^Any cal
34bd0 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70  lback set by a p
34be0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
34bf0 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
34c00 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74  _hook().** for t
34c10 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
34c20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
34c30 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54  verridden..** ^T
34c40 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
34c50 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
34c60 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  gh to the callba
34c70 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63  ck..** ^If the c
34c80 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d  allback on a com
34c90 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f  mit hook functio
34ca0 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  n returns non-ze
34cb0 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ro,.** then the 
34cc0 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72  commit is conver
34cd0 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62  ted into a rollb
34ce0 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ack..**.** ^The 
34cf0 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
34d00 6f 6f 6b 28 44 2c 43 2c 50 29 20 61 6e 64 20 73  ook(D,C,P) and s
34d10 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
34d20 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63  hook(D,C,P) func
34d30 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20  tions.** return 
34d40 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66  the P argument f
34d50 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73  rom the previous
34d60 20 63 61 6c 6c 20 6f 66 20 74 68 65 20 73 61 6d   call of the sam
34d70 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6f 6e  e function.** on
34d80 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
34d90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
34da0 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a  D, or NULL for.*
34db0 2a 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  * the first call
34dc0 20 66 6f 72 20 65 61 63 68 20 66 75 6e 63 74 69   for each functi
34dd0 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 54  on on D..**.** T
34de0 68 65 20 63 6f 6d 6d 69 74 20 61 6e 64 20 72 6f  he commit and ro
34df0 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 63 61 6c 6c  llback hook call
34e00 62 61 63 6b 73 20 61 72 65 20 6e 6f 74 20 72 65  backs are not re
34e10 65 6e 74 72 61 6e 74 2e 0a 2a 2a 20 54 68 65 20  entrant..** The 
34e20 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65  callback impleme
34e30 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ntation must not
34e40 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
34e50 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
34e60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
34e70 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
34e80 76 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 61  voked the callba
34e90 63 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73  ck.  Any actions
34ea0 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68  .** to modify th
34eb0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
34ec0 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65  ction must be de
34ed0 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74  ferred until aft
34ee0 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65  er the.** comple
34ef0 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c  tion of the [sql
34f00 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c  ite3_step()] cal
34f10 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
34f20 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f   the commit.** o
34f30 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20  r rollback hook 
34f40 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61  in the first pla
34f50 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ce..** Note that
34f60 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 6f 74 68   running any oth
34f70 65 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  er SQL statement
34f80 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 53 45 4c  s, including SEL
34f90 45 43 54 20 73 74 61 74 65 6d 65 6e 74 73 2c 0a  ECT statements,.
34fa0 2a 2a 20 6f 72 20 6d 65 72 65 6c 79 20 63 61 6c  ** or merely cal
34fb0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  ling [sqlite3_pr
34fc0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
34fd0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
34fe0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
34ff0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
35000 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
35010 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
35020 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
35030 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52  agraph..**.** ^R
35040 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c  egistering a NUL
35050 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62  L function disab
35060 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  les the callback
35070 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  ..**.** ^When th
35080 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61  e commit hook ca
35090 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72  llback routine r
350a0 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65  eturns zero, the
350b0 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65   [COMMIT].** ope
350c0 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77 65  ration is allowe
350d0 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 6e 6f  d to continue no
350e0 72 6d 61 6c 6c 79 2e 20 20 5e 49 66 20 74 68 65  rmally.  ^If the
350f0 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20   commit hook.** 
35100 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
35110 2c 20 74 68 65 6e 20 74 68 65 20 5b 43 4f 4d 4d  , then the [COMM
35120 49 54 5d 20 69 73 20 63 6f 6e 76 65 72 74 65 64  IT] is converted
35130 20 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42 41 43   into a [ROLLBAC
35140 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c  K]..** ^The roll
35150 62 61 63 6b 20 68 6f 6f 6b 20 69 73 20 69 6e 76  back hook is inv
35160 6f 6b 65 64 20 6f 6e 20 61 20 72 6f 6c 6c 62 61  oked on a rollba
35170 63 6b 20 74 68 61 74 20 72 65 73 75 6c 74 73 20  ck that results 
35180 66 72 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a  from a commit.**
35190 20 68 6f 6f 6b 20 72 65 74 75 72 6e 69 6e 67 20   hook returning 
351a0 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74 20 61  non-zero, just a
351b0 73 20 69 74 20 77 6f 75 6c 64 20 62 65 20 77 69  s it would be wi
351c0 74 68 20 61 6e 79 20 6f 74 68 65 72 20 72 6f 6c  th any other rol
351d0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f  lback..**.** ^Fo
351e0 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
351f0 66 20 74 68 69 73 20 41 50 49 2c 20 61 20 74 72  f this API, a tr
35200 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69  ansaction is sai
35210 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a  d to have been.*
35220 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66  * rolled back if
35230 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f   an explicit "RO
35240 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e  LLBACK" statemen
35250 74 20 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f  t is executed, o
35260 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72  r.** an error or
35270 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73   constraint caus
35280 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72  es an implicit r
35290 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72  ollback to occur
352a0 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61  ..** ^The rollba
352b0 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e  ck callback is n
352c0 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20  ot invoked if a 
352d0 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a  transaction is.*
352e0 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
352f0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61  rolled back beca
35300 75 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  use the database
35310 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
35320 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  losed..**.** See
35330 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
35340 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29  e3_update_hook()
35350 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a  ] interface..*/.
35360 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
35370 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65  mmit_hook(sqlite
35380 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  3*, int(*)(void*
35390 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20  ), void*);.void 
353a0 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  *sqlite3_rollbac
353b0 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c  k_hook(sqlite3*,
353c0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29   void(*)(void *)
353d0 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
353e0 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20   CAPI3REF: Data 
353f0 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74  Change Notificat
35400 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ion Callbacks.**
35410 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
35420 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69  _update_hook() i
35430 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
35440 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
35450 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
35460 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
35470 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66  nection] identif
35480 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ied by the first
35490 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
354a0 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
354b0 76 65 72 20 61 20 72 6f 77 20 69 73 20 75 70 64  ver a row is upd
354c0 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  ated, inserted o
354d0 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 41  r deleted..** ^A
354e0 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
354f0 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
35500 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  ll to this funct
35510 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  ion.** for the s
35520 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
35530 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
35540 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  idden..**.** ^Th
35550 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
35560 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
35570 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74  o the function t
35580 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a  o invoke when a.
35590 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74 65  ** row is update
355a0 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  d, inserted or d
355b0 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  eleted..** ^The 
355c0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
355d0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
355e0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
355f0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a  third argument.*
35600 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64  * to sqlite3_upd
35610 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 5e  ate_hook()..** ^
35620 54 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62  The second callb
35630 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ack argument is 
35640 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
35650 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  NSERT], [SQLITE_
35660 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  DELETE],.** or [
35670 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 20  SQLITE_UPDATE], 
35680 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
35690 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
356a0 63 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62  caused the callb
356b0 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76  ack.** to be inv
356c0 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 74 68  oked..** ^The th
356d0 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61  ird and fourth a
356e0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20  rguments to the 
356f0 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
35700 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65   pointers to the
35710 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 61 6e 64  .** database and
35720 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74   table name cont
35730 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63  aining the affec
35740 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 5e 54 68 65  ted row..** ^The
35750 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20   final callback 
35760 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
35770 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
35780 72 6f 77 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  row..** ^In the 
35790 63 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74  case of an updat
357a0 65 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 5b  e, this is the [
357b0 72 6f 77 69 64 5d 20 61 66 74 65 72 20 74 68 65  rowid] after the
357c0 20 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c   update takes pl
357d0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ace..**.** ^(The
357e0 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20   update hook is 
357f0 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e  not invoked when
35800 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d   internal system
35810 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d   tables are.** m
35820 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71  odified (i.e. sq
35830 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20  lite_master and 
35840 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29  sqlite_sequence)
35850 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68  .)^.**.** ^In th
35860 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d  e current implem
35870 65 6e 74 61 74 69 6f 6e 2c 20 74 68 65 20 75 70  entation, the up
35880 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 73 20  date hook.** is 
35890 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e  not invoked when
358a0 20 64 75 70 6c 69 63 61 74 69 6f 6e 20 72 6f 77   duplication row
358b0 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 62 65  s are deleted be
358c0 63 61 75 73 65 20 6f 66 20 61 6e 0a 2a 2a 20 5b  cause of an.** [
358d0 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 7c 20 4f 4e  ON CONFLICT | ON
358e0 20 43 4f 4e 46 4c 49 43 54 20 52 45 50 4c 41 43   CONFLICT REPLAC
358f0 45 5d 20 63 6c 61 75 73 65 2e 20 20 5e 4e 6f 72  E] clause.  ^Nor
35900 20 69 73 20 74 68 65 20 75 70 64 61 74 65 20 68   is the update h
35910 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 77  ook.** invoked w
35920 68 65 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c  hen rows are del
35930 65 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  eted using the [
35940 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a  truncate optimiz
35950 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 65  ation]..** The e
35960 78 63 65 70 74 69 6f 6e 73 20 64 65 66 69 6e 65  xceptions define
35970 64 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  d in this paragr
35980 61 70 68 20 6d 69 67 68 74 20 63 68 61 6e 67 65  aph might change
35990 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20   in a future.** 
359a0 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
359b0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64  e..**.** The upd
359c0 61 74 65 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65  ate hook impleme
359d0 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ntation must not
359e0 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
359f0 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
35a00 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
35a10 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
35a20 76 6f 6b 65 64 20 74 68 65 20 75 70 64 61 74 65  voked the update
35a30 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 61 63 74 69   hook.  Any acti
35a40 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79  ons.** to modify
35a50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
35a60 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  nnection must be
35a70 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
35a80 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d  after the.** com
35a90 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b  pletion of the [
35aa0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
35ab0 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
35ac0 72 65 64 20 74 68 65 20 75 70 64 61 74 65 20 68  red the update h
35ad0 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ook..** Note tha
35ae0 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
35af0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
35b00 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
35b10 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
35b20 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
35b30 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
35b40 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
35b50 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
35b60 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  graph..**.** ^Th
35b70 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65  e sqlite3_update
35b80 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e  _hook(D,C,P) fun
35b90 63 74 69 6f 6e 0a 2a 2a 20 72 65 74 75 72 6e 73  ction.** returns
35ba0 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20   the P argument 
35bb0 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75  from the previou
35bc0 73 20 63 61 6c 6c 0a 2a 2a 20 6f 6e 20 74 68 65  s call.** on the
35bd0 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
35be0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f  connection] D, o
35bf0 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68  r NULL for.** th
35c00 65 20 66 69 72 73 74 20 63 61 6c 6c 20 6f 6e 20  e first call on 
35c10 44 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  D..**.** See als
35c20 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
35c30 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 61 6e  ommit_hook()] an
35c40 64 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  d [sqlite3_rollb
35c50 61 63 6b 5f 68 6f 6f 6b 28 29 5d 0a 2a 2a 20 69  ack_hook()].** i
35c60 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2f 0a 76 6f  nterfaces..*/.vo
35c70 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70 64 61  id *sqlite3_upda
35c80 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74  te_hook(.  sqlit
35c90 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28  e3*, .  void(*)(
35ca0 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72  void *,int ,char
35cb0 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f   const *,char co
35cc0 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  nst *,sqlite3_in
35cd0 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b  t64),.  void*.);
35ce0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35cf0 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
35d00 62 6c 65 20 53 68 61 72 65 64 20 50 61 67 65 72  ble Shared Pager
35d10 20 43 61 63 68 65 0a 2a 2a 20 4b 45 59 57 4f 52   Cache.** KEYWOR
35d20 44 53 3a 20 7b 73 68 61 72 65 64 20 63 61 63 68  DS: {shared cach
35d30 65 7d 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  e}.**.** ^(This 
35d40 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20  routine enables 
35d50 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  or disables the 
35d60 73 68 61 72 69 6e 67 20 6f 66 20 74 68 65 20 64  sharing of the d
35d70 61 74 61 62 61 73 65 20 63 61 63 68 65 0a 2a 2a  atabase cache.**
35d80 20 61 6e 64 20 73 63 68 65 6d 61 20 64 61 74 61   and schema data
35d90 20 73 74 72 75 63 74 75 72 65 73 20 62 65 74 77   structures betw
35da0 65 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  een [database co
35db0 6e 6e 65 63 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65  nnection | conne
35dc0 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68  ctions].** to th
35dd0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 2e  e same database.
35de0 20 53 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62   Sharing is enab
35df0 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d  led if the argum
35e00 65 6e 74 20 69 73 20 74 72 75 65 0a 2a 2a 20 61  ent is true.** a
35e10 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66 20 74  nd disabled if t
35e20 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 66  he argument is f
35e30 61 6c 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43  alse.)^.**.** ^C
35e40 61 63 68 65 20 73 68 61 72 69 6e 67 20 69 73 20  ache sharing is 
35e50 65 6e 61 62 6c 65 64 20 61 6e 64 20 64 69 73 61  enabled and disa
35e60 62 6c 65 64 20 66 6f 72 20 61 6e 20 65 6e 74 69  bled for an enti
35e70 72 65 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 20 54  re process..** T
35e80 68 69 73 20 69 73 20 61 20 63 68 61 6e 67 65 20  his is a change 
35e90 61 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72  as of SQLite ver
35ea0 73 69 6f 6e 20 33 2e 35 2e 30 2e 20 49 6e 20 70  sion 3.5.0. In p
35eb0 72 69 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  rior versions of
35ec0 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 73 68 61 72   SQLite,.** shar
35ed0 69 6e 67 20 77 61 73 20 65 6e 61 62 6c 65 64 20  ing was enabled 
35ee0 6f 72 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20  or disabled for 
35ef0 65 61 63 68 20 74 68 72 65 61 64 20 73 65 70 61  each thread sepa
35f00 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28  rately..**.** ^(
35f10 54 68 65 20 63 61 63 68 65 20 73 68 61 72 69 6e  The cache sharin
35f20 67 20 6d 6f 64 65 20 73 65 74 20 62 79 20 74 68  g mode set by th
35f30 69 73 20 69 6e 74 65 72 66 61 63 65 20 65 66 66  is interface eff
35f40 65 63 74 73 20 61 6c 6c 20 73 75 62 73 65 71 75  ects all subsequ
35f50 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
35f60 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
35f70 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
35f80 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  v2()], and [sqli
35f90 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a  te3_open16()]..*
35fa0 2a 20 45 78 69 73 74 69 6e 67 20 64 61 74 61 62  * Existing datab
35fb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
35fc0 63 6f 6e 74 69 6e 75 65 20 75 73 65 20 74 68 65  continue use the
35fd0 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a   sharing mode.**
35fe0 20 74 68 61 74 20 77 61 73 20 69 6e 20 65 66 66   that was in eff
35ff0 65 63 74 20 61 74 20 74 68 65 20 74 69 6d 65 20  ect at the time 
36000 74 68 65 79 20 77 65 72 65 20 6f 70 65 6e 65 64  they were opened
36010 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  .)^.**.** ^(This
36020 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
36030 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20   [SQLITE_OK] if 
36040 73 68 61 72 65 64 20 63 61 63 68 65 20 77 61 73  shared cache was
36050 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
36060 62 6c 65 64 0a 2a 2a 20 73 75 63 63 65 73 73 66  bled.** successf
36070 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72  ully.  An [error
36080 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
36090 65 64 20 6f 74 68 65 72 77 69 73 65 2e 29 5e 0a  ed otherwise.)^.
360a0 2a 2a 0a 2a 2a 20 5e 53 68 61 72 65 64 20 63 61  **.** ^Shared ca
360b0 63 68 65 20 69 73 20 64 69 73 61 62 6c 65 64 20  che is disabled 
360c0 62 79 20 64 65 66 61 75 6c 74 2e 20 42 75 74 20  by default. But 
360d0 74 68 69 73 20 6d 69 67 68 74 20 63 68 61 6e 67  this might chang
360e0 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72  e in.** future r
360f0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
36100 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  e.  Applications
36110 20 74 68 61 74 20 63 61 72 65 20 61 62 6f 75 74   that care about
36120 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65   shared.** cache
36130 20 73 65 74 74 69 6e 67 20 73 68 6f 75 6c 64 20   setting should 
36140 73 65 74 20 69 74 20 65 78 70 6c 69 63 69 74 6c  set it explicitl
36150 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c 73  y..**.** See Als
36160 6f 3a 20 20 5b 53 51 4c 69 74 65 20 53 68 61 72  o:  [SQLite Shar
36170 65 64 2d 43 61 63 68 65 20 4d 6f 64 65 5d 0a 2a  ed-Cache Mode].*
36180 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e  /.int sqlite3_en
36190 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
361a0 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e(int);../*.** C
361b0 41 50 49 33 52 45 46 3a 20 41 74 74 65 6d 70 74  API3REF: Attempt
361c0 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65   To Free Heap Me
361d0 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  mory.**.** ^The 
361e0 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
361f0 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 61  memory() interfa
36200 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 66  ce attempts to f
36210 72 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20 6f  ree N bytes.** o
36220 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79  f heap memory by
36230 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f   deallocating no
36240 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f  n-essential memo
36250 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a  ry allocations.*
36260 2a 20 68 65 6c 64 20 62 79 20 74 68 65 20 64 61  * held by the da
36270 74 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e 20  tabase library. 
36280 20 20 4d 65 6d 6f 72 79 20 75 73 65 64 20 74 6f    Memory used to
36290 20 63 61 63 68 65 20 64 61 74 61 62 61 73 65 0a   cache database.
362a0 2a 2a 20 70 61 67 65 73 20 74 6f 20 69 6d 70 72  ** pages to impr
362b0 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ove performance 
362c0 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  is an example of
362d0 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d   non-essential m
362e0 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 73 71 6c 69 74  emory..** ^sqlit
362f0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
36300 79 28 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  y() returns the 
36310 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
36320 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 0a  actually freed,.
36330 2a 2a 20 77 68 69 63 68 20 6d 69 67 68 74 20 62  ** which might b
36340 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 20 74  e more or less t
36350 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72  han the amount r
36360 65 71 75 65 73 74 65 64 2e 0a 2a 2a 20 5e 54 68  equested..** ^Th
36370 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73  e sqlite3_releas
36380 65 5f 6d 65 6d 6f 72 79 28 29 20 72 6f 75 74 69  e_memory() routi
36390 6e 65 20 69 73 20 61 20 6e 6f 2d 6f 70 20 72 65  ne is a no-op re
363a0 74 75 72 6e 69 6e 67 20 7a 65 72 6f 0a 2a 2a 20  turning zero.** 
363b0 69 66 20 53 51 4c 69 74 65 20 69 73 20 6e 6f 74  if SQLite is not
363c0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b   compiled with [
363d0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
363e0 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d  MORY_MANAGEMENT]
363f0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
36400 3a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 72 65  : [sqlite3_db_re
36410 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a  lease_memory()].
36420 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
36430 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e  elease_memory(in
36440 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
36450 52 45 46 3a 20 46 72 65 65 20 4d 65 6d 6f 72 79  REF: Free Memory
36460 20 55 73 65 64 20 42 79 20 41 20 44 61 74 61 62   Used By A Datab
36470 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
36480 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
36490 33 5f 64 62 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  3_db_release_mem
364a0 6f 72 79 28 44 29 20 69 6e 74 65 72 66 61 63 65  ory(D) interface
364b0 20 61 74 74 65 6d 70 74 73 20 74 6f 20 66 72 65   attempts to fre
364c0 65 20 61 73 20 6d 75 63 68 20 68 65 61 70 0a 2a  e as much heap.*
364d0 2a 20 6d 65 6d 6f 72 79 20 61 73 20 70 6f 73 73  * memory as poss
364e0 69 62 6c 65 20 66 72 6f 6d 20 64 61 74 61 62 61  ible from databa
364f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
36500 20 55 6e 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 5b   Unlike the.** [
36510 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
36520 6d 65 6d 6f 72 79 28 29 5d 20 69 6e 74 65 72 66  memory()] interf
36530 61 63 65 2c 20 74 68 69 73 20 69 6e 74 65 72 66  ace, this interf
36540 61 63 65 20 69 73 20 65 66 66 65 63 74 20 65 76  ace is effect ev
36550 65 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 6e 20  en.** when then 
36560 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
36570 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54  EMORY_MANAGEMENT
36580 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
36590 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 6f 6d 69 74  ption is.** omit
365a0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ted..**.** See a
365b0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 72 65  lso: [sqlite3_re
365c0 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a  lease_memory()].
365d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
365e0 62 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  b_release_memory
365f0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
36600 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6d 70  ** CAPI3REF: Imp
36610 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48  ose A Limit On H
36620 65 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a 2a 20 5e  eap Size.**.** ^
36630 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 74  The sqlite3_soft
36640 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20  _heap_limit64() 
36650 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 61  interface sets a
36660 6e 64 2f 6f 72 20 71 75 65 72 69 65 73 20 74 68  nd/or queries th
36670 65 0a 2a 2a 20 73 6f 66 74 20 6c 69 6d 69 74 20  e.** soft limit 
36680 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66  on the amount of
36690 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61   heap memory tha
366a0 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74  t may be allocat
366b0 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a  ed by SQLite..**
366c0 20 5e 53 51 4c 69 74 65 20 73 74 72 69 76 65 73   ^SQLite strives
366d0 20 74 6f 20 6b 65 65 70 20 68 65 61 70 20 6d 65   to keep heap me
366e0 6d 6f 72 79 20 75 74 69 6c 69 7a 61 74 69 6f 6e  mory utilization
366f0 20 62 65 6c 6f 77 20 74 68 65 20 73 6f 66 74 20   below the soft 
36700 68 65 61 70 0a 2a 2a 20 6c 69 6d 69 74 20 62 79  heap.** limit by
36710 20 72 65 64 75 63 69 6e 67 20 74 68 65 20 6e 75   reducing the nu
36720 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 68 65  mber of pages he
36730 6c 64 20 69 6e 20 74 68 65 20 70 61 67 65 20 63  ld in the page c
36740 61 63 68 65 0a 2a 2a 20 61 73 20 68 65 61 70 20  ache.** as heap 
36750 6d 65 6d 6f 72 79 20 75 73 61 67 65 73 20 61 70  memory usages ap
36760 70 72 6f 61 63 68 65 73 20 74 68 65 20 6c 69 6d  proaches the lim
36770 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 6f 66 74  it..** ^The soft
36780 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 22   heap limit is "
36790 73 6f 66 74 22 20 62 65 63 61 75 73 65 20 65 76  soft" because ev
367a0 65 6e 20 74 68 6f 75 67 68 20 53 51 4c 69 74 65  en though SQLite
367b0 20 73 74 72 69 76 65 73 20 74 6f 20 73 74 61 79   strives to stay
367c0 0a 2a 2a 20 62 65 6c 6f 77 20 74 68 65 20 6c 69  .** below the li
367d0 6d 69 74 2c 20 69 74 20 77 69 6c 6c 20 65 78 63  mit, it will exc
367e0 65 65 64 20 74 68 65 20 6c 69 6d 69 74 20 72 61  eed the limit ra
367f0 74 68 65 72 20 74 68 61 6e 20 67 65 6e 65 72 61  ther than genera
36800 74 65 0a 2a 2a 20 61 6e 20 5b 53 51 4c 49 54 45  te.** an [SQLITE
36810 5f 4e 4f 4d 45 4d 5d 20 65 72 72 6f 72 2e 20 20  _NOMEM] error.  
36820 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
36830 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
36840 6d 69 74 20 0a 2a 2a 20 69 73 20 61 64 76 69 73  mit .** is advis
36850 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ory only..**.** 
36860 5e 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  ^The return valu
36870 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 73  e from sqlite3_s
36880 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
36890 28 29 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f  () is the size o
368a0 66 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20 68 65  f.** the soft he
368b0 61 70 20 6c 69 6d 69 74 20 70 72 69 6f 72 20 74  ap limit prior t
368c0 6f 20 74 68 65 20 63 61 6c 6c 2c 20 6f 72 20 6e  o the call, or n
368d0 65 67 61 74 69 76 65 20 69 6e 20 74 68 65 20 63  egative in the c
368e0 61 73 65 20 6f 66 20 61 6e 0a 2a 2a 20 65 72 72  ase of an.** err
368f0 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 72 67  or.  ^If the arg
36900 75 6d 65 6e 74 20 4e 20 69 73 20 6e 65 67 61 74  ument N is negat
36910 69 76 65 0a 2a 2a 20 74 68 65 6e 20 6e 6f 20 63  ive.** then no c
36920 68 61 6e 67 65 20 69 73 20 6d 61 64 65 20 74 6f  hange is made to
36930 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
36940 69 6d 69 74 2e 20 20 48 65 6e 63 65 2c 20 74 68  imit.  Hence, th
36950 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 73 69 7a  e current.** siz
36960 65 20 6f 66 20 74 68 65 20 73 6f 66 74 20 68 65  e of the soft he
36970 61 70 20 6c 69 6d 69 74 20 63 61 6e 20 62 65 20  ap limit can be 
36980 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 69 6e  determined by in
36990 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  voking.** sqlite
369a0 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
369b0 74 36 34 28 29 20 77 69 74 68 20 61 20 6e 65 67  t64() with a neg
369c0 61 74 69 76 65 20 61 72 67 75 6d 65 6e 74 2e 0a  ative argument..
369d0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 72  **.** ^If the ar
369e0 67 75 6d 65 6e 74 20 4e 20 69 73 20 7a 65 72 6f  gument N is zero
369f0 20 74 68 65 6e 20 74 68 65 20 73 6f 66 74 20 68   then the soft h
36a00 65 61 70 20 6c 69 6d 69 74 20 69 73 20 64 69 73  eap limit is dis
36a10 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  abled..**.** ^(T
36a20 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
36a30 69 74 20 69 73 20 6e 6f 74 20 65 6e 66 6f 72 63  it is not enforc
36a40 65 64 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  ed in the curren
36a50 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
36a60 0a 2a 2a 20 69 66 20 6f 6e 65 20 6f 72 20 6d 6f  .** if one or mo
36a70 72 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 20  re of following 
36a80 63 6f 6e 64 69 74 69 6f 6e 73 20 61 72 65 20 74  conditions are t
36a90 72 75 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  rue:.**.** <ul>.
36aa0 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 73 6f 66 74  ** <li> The soft
36ab0 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 73   heap limit is s
36ac0 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 20 3c  et to zero..** <
36ad0 6c 69 3e 20 4d 65 6d 6f 72 79 20 61 63 63 6f 75  li> Memory accou
36ae0 6e 74 69 6e 67 20 69 73 20 64 69 73 61 62 6c 65  nting is disable
36af0 64 20 75 73 69 6e 67 20 61 20 63 6f 6d 62 69 6e  d using a combin
36b00 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  ation of the.** 
36b10 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
36b20 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f  nfig]([SQLITE_CO
36b30 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 2c  NFIG_MEMSTATUS],
36b40 2e 2e 2e 29 20 73 74 61 72 74 2d 74 69 6d 65 20  ...) start-time 
36b50 6f 70 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20  option and.**   
36b60 20 20 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44     the [SQLITE_D
36b70 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53  EFAULT_MEMSTATUS
36b80 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
36b90 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 41  ption..** <li> A
36ba0 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 20 70 61  n alternative pa
36bb0 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
36bc0 6e 74 61 74 69 6f 6e 20 69 73 20 73 70 65 63 69  ntation is speci
36bd0 66 69 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20  fied using.**   
36be0 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66     [sqlite3_conf
36bf0 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ig]([SQLITE_CONF
36c00 49 47 5f 50 43 41 43 48 45 32 5d 2c 2e 2e 2e 29  IG_PCACHE2],...)
36c10 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 70 61  ..** <li> The pa
36c20 67 65 20 63 61 63 68 65 20 61 6c 6c 6f 63 61 74  ge cache allocat
36c30 65 73 20 66 72 6f 6d 20 69 74 73 20 6f 77 6e 20  es from its own 
36c40 6d 65 6d 6f 72 79 20 70 6f 6f 6c 20 73 75 70 70  memory pool supp
36c50 6c 69 65 64 0a 2a 2a 20 20 20 20 20 20 62 79 20  lied.**      by 
36c60 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
36c70 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
36c80 50 41 47 45 43 41 43 48 45 5d 2c 2e 2e 2e 29 20  PAGECACHE],...) 
36c90 72 61 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20  rather than.**  
36ca0 20 20 20 20 66 72 6f 6d 20 74 68 65 20 68 65 61      from the hea
36cb0 70 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  p..** </ul>)^.**
36cc0 0a 2a 2a 20 42 65 67 69 6e 6e 69 6e 67 20 77 69  .** Beginning wi
36cd0 74 68 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  th SQLite versio
36ce0 6e 20 33 2e 37 2e 33 2c 20 74 68 65 20 73 6f 66  n 3.7.3, the sof
36cf0 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20  t heap limit is 
36d00 65 6e 66 6f 72 63 65 64 0a 2a 2a 20 72 65 67 61  enforced.** rega
36d10 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
36d20 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51  r or not the [SQ
36d30 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f  LITE_ENABLE_MEMO
36d40 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 0a 2a  RY_MANAGEMENT].*
36d50 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
36d60 70 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ption is invoked
36d70 2e 20 20 57 69 74 68 20 5b 53 51 4c 49 54 45 5f  .  With [SQLITE_
36d80 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41  ENABLE_MEMORY_MA
36d90 4e 41 47 45 4d 45 4e 54 5d 2c 0a 2a 2a 20 74 68  NAGEMENT],.** th
36da0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
36db0 74 20 69 73 20 65 6e 66 6f 72 63 65 64 20 6f 6e  t is enforced on
36dc0 20 65 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c   every memory al
36dd0 6c 6f 63 61 74 69 6f 6e 2e 20 20 57 69 74 68 6f  location.  Witho
36de0 75 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  ut.** [SQLITE_EN
36df0 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41  ABLE_MEMORY_MANA
36e00 47 45 4d 45 4e 54 5d 2c 20 74 68 65 20 73 6f 66  GEMENT], the sof
36e10 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20  t heap limit is 
36e20 6f 6e 6c 79 20 65 6e 66 6f 72 63 65 64 0a 2a 2a  only enforced.**
36e30 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20   when memory is 
36e40 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 74 68 65  allocated by the
36e50 20 70 61 67 65 20 63 61 63 68 65 2e 20 20 54 65   page cache.  Te
36e60 73 74 69 6e 67 20 73 75 67 67 65 73 74 73 20 74  sting suggests t
36e70 68 61 74 20 62 65 63 61 75 73 65 0a 2a 2a 20 74  hat because.** t
36e80 68 65 20 70 61 67 65 20 63 61 63 68 65 20 69 73  he page cache is
36e90 20 74 68 65 20 70 72 65 64 6f 6d 69 6e 61 74 65   the predominate
36ea0 20 6d 65 6d 6f 72 79 20 75 73 65 72 20 69 6e 20   memory user in 
36eb0 53 51 4c 69 74 65 2c 20 6d 6f 73 74 0a 2a 2a 20  SQLite, most.** 
36ec0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 6c  applications wil
36ed0 6c 20 61 63 68 69 65 76 65 20 61 64 65 71 75 61  l achieve adequa
36ee0 74 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  te soft heap lim
36ef0 69 74 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 77  it enforcement w
36f00 69 74 68 6f 75 74 0a 2a 2a 20 74 68 65 20 75 73  ithout.** the us
36f10 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e of [SQLITE_ENA
36f20 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47  BLE_MEMORY_MANAG
36f30 45 4d 45 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  EMENT]..**.** Th
36f40 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20  e circumstances 
36f50 75 6e 64 65 72 20 77 68 69 63 68 20 53 51 4c 69  under which SQLi
36f60 74 65 20 77 69 6c 6c 20 65 6e 66 6f 72 63 65 20  te will enforce 
36f70 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
36f80 6d 69 74 20 6d 61 79 0a 2a 2a 20 63 68 61 6e 67  mit may.** chang
36f90 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  es in future rel
36fa0 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
36fb0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
36fc0 34 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68  4 sqlite3_soft_h
36fd0 65 61 70 5f 6c 69 6d 69 74 36 34 28 73 71 6c 69  eap_limit64(sqli
36fe0 74 65 33 5f 69 6e 74 36 34 20 4e 29 3b 0a 0a 2f  te3_int64 N);../
36ff0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
37000 65 70 72 65 63 61 74 65 64 20 53 6f 66 74 20 48  eprecated Soft H
37010 65 61 70 20 4c 69 6d 69 74 20 49 6e 74 65 72 66  eap Limit Interf
37020 61 63 65 0a 2a 2a 20 44 45 50 52 45 43 41 54 45  ace.** DEPRECATE
37030 44 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  D.**.** This is 
37040 61 20 64 65 70 72 65 63 61 74 65 64 20 76 65 72  a deprecated ver
37050 73 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c  sion of the [sql
37060 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
37070 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 69 6e 74  imit64()].** int
37080 65 72 66 61 63 65 2e 20 20 54 68 69 73 20 72 6f  erface.  This ro
37090 75 74 69 6e 65 20 69 73 20 70 72 6f 76 69 64 65  utine is provide
370a0 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  d for historical
370b0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a   compatibility.*
370c0 2a 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6e 65 77  * only.  All new
370d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   applications sh
370e0 6f 75 6c 64 20 75 73 65 20 74 68 65 0a 2a 2a 20  ould use the.** 
370f0 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
37100 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 20 69 6e  ap_limit64()] in
37110 74 65 72 66 61 63 65 20 72 61 74 68 65 72 20 74  terface rather t
37120 68 61 6e 20 74 68 69 73 20 6f 6e 65 2e 0a 2a 2f  han this one..*/
37130 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
37140 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  ED void sqlite3_
37150 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28  soft_heap_limit(
37160 69 6e 74 20 4e 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  int N);.../*.** 
37170 43 41 50 49 33 52 45 46 3a 20 45 78 74 72 61 63  CAPI3REF: Extrac
37180 74 20 4d 65 74 61 64 61 74 61 20 41 62 6f 75 74  t Metadata About
37190 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54   A Column Of A T
371a0 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  able.**.** ^This
371b0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
371c0 20 6d 65 74 61 64 61 74 61 20 61 62 6f 75 74 20   metadata about 
371d0 61 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d  a specific colum
371e0 6e 20 6f 66 20 61 20 73 70 65 63 69 66 69 63 0a  n of a specific.
371f0 2a 2a 20 64 61 74 61 62 61 73 65 20 74 61 62 6c  ** database tabl
37200 65 20 61 63 63 65 73 73 69 62 6c 65 20 75 73 69  e accessible usi
37210 6e 67 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  ng the [database
37220 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
37230 64 6c 65 0a 2a 2a 20 70 61 73 73 65 64 20 61 73  dle.** passed as
37240 20 74 68 65 20 66 69 72 73 74 20 66 75 6e 63 74   the first funct
37250 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
37260 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 75 6d 6e 20  .** ^The column 
37270 69 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  is identified by
37280 20 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69   the second, thi
37290 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61  rd and fourth pa
372a0 72 61 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74  rameters to.** t
372b0 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 54  his function. ^T
372c0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
372d0 74 65 72 20 69 73 20 65 69 74 68 65 72 20 74 68  ter is either th
372e0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
372f0 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20  tabase.** (i.e. 
37300 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20  "main", "temp", 
37310 6f 72 20 61 6e 20 61 74 74 61 63 68 65 64 20 64  or an attached d
37320 61 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e  atabase) contain
37330 69 6e 67 20 74 68 65 20 73 70 65 63 69 66 69 65  ing the specifie
37340 64 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55  d.** table or NU
37350 4c 4c 2e 20 5e 49 66 20 69 74 20 69 73 20 4e 55  LL. ^If it is NU
37360 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74  LL, then all att
37370 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 20  ached databases 
37380 61 72 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20  are searched.** 
37390 66 6f 72 20 74 68 65 20 74 61 62 6c 65 20 75 73  for the table us
373a0 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67  ing the same alg
373b0 6f 72 69 74 68 6d 20 75 73 65 64 20 62 79 20 74  orithm used by t
373c0 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
373d0 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65  ne to.** resolve
373e0 20 75 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62   unqualified tab
373f0 6c 65 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a  le references..*
37400 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
37410 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d  and fourth param
37420 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75  eters to this fu
37430 6e 63 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74  nction are the t
37440 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a  able and column.
37450 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  ** name of the d
37460 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72  esired column, r
37470 65 73 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69  espectively. Nei
37480 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 70 61  ther of these pa
37490 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20  rameters.** may 
374a0 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  be NULL..**.** ^
374b0 4d 65 74 61 64 61 74 61 20 69 73 20 72 65 74 75  Metadata is retu
374c0 72 6e 65 64 20 62 79 20 77 72 69 74 69 6e 67 20  rned by writing 
374d0 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f  to the memory lo
374e0 63 61 74 69 6f 6e 73 20 70 61 73 73 65 64 20 61  cations passed a
374f0 73 20 74 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64  s the 5th.** and
37500 20 73 75 62 73 65 71 75 65 6e 74 20 70 61 72 61   subsequent para
37510 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66  meters to this f
37520 75 6e 63 74 69 6f 6e 2e 20 5e 41 6e 79 20 6f 66  unction. ^Any of
37530 20 74 68 65 73 65 20 61 72 67 75 6d 65 6e 74 73   these arguments
37540 20 6d 61 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c   may be.** NULL,
37550 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74   in which case t
37560 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
37570 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61   element of meta
37580 64 61 74 61 20 69 73 20 6f 6d 69 74 74 65 64 2e  data is omitted.
37590 0a 2a 2a 0a 2a 2a 20 5e 28 3c 62 6c 6f 63 6b 71  .**.** ^(<blockq
375a0 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20  uote>.** <table 
375b0 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c  border="1">.** <
375c0 74 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74 65  tr><th> Paramete
375d0 72 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62 72  r <th> Output<br
375e0 3e 54 79 70 65 20 3c 74 68 3e 20 20 44 65 73 63  >Type <th>  Desc
375f0 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  ription.**.** <t
37600 72 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e 20  r><td> 5th <td> 
37610 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e  const char* <td>
37620 20 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74   Data type.** <t
37630 72 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e 20  r><td> 6th <td> 
37640 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e  const char* <td>
37650 20 4e 61 6d 65 20 6f 66 20 64 65 66 61 75 6c 74   Name of default
37660 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
37670 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nce.** <tr><td> 
37680 37 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20  7th <td> int    
37690 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69       <td> True i
376a0 66 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e  f column has a N
376b0 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69  OT NULL constrai
376c0 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38  nt.** <tr><td> 8
376d0 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20  th <td> int     
376e0 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66      <td> True if
376f0 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20   column is part 
37700 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b  of the PRIMARY K
37710 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39  EY.** <tr><td> 9
37720 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20  th <td> int     
37730 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66      <td> True if
37740 20 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f   column is [AUTO
37750 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f  INCREMENT].** </
37760 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63  table>.** </bloc
37770 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
37780 5e 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  ^The memory poin
37790 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 63 68  ted to by the ch
377a0 61 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73  aracter pointers
377b0 20 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68   returned for th
377c0 65 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e  e.** declaration
377d0 20 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74   type and collat
377e0 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20  ion sequence is 
377f0 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c  valid only until
37800 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c   the next.** cal
37810 6c 20 74 6f 20 61 6e 79 20 53 51 4c 69 74 65 20  l to any SQLite 
37820 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  API function..**
37830 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63  .** ^If the spec
37840 69 66 69 65 64 20 74 61 62 6c 65 20 69 73 20 61  ified table is a
37850 63 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20  ctually a view, 
37860 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
37870 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
37880 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69  ** ^If the speci
37890 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22  fied column is "
378a0 72 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72  rowid", "oid" or
378b0 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61   "_rowid_" and a
378c0 6e 0a 2a 2a 20 5b 49 4e 54 45 47 45 52 20 50 52  n.** [INTEGER PR
378d0 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d  IMARY KEY] colum
378e0 6e 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69  n has been expli
378f0 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20  citly declared, 
37900 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a  then the output.
37910 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  ** parameters ar
37920 65 20 73 65 74 20 66 6f 72 20 74 68 65 20 65 78  e set for the ex
37930 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
37940 64 20 63 6f 6c 75 6d 6e 2e 20 5e 28 49 66 20 74  d column. ^(If t
37950 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78  here is no.** ex
37960 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
37970 64 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41  d [INTEGER PRIMA
37980 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20  RY KEY] column, 
37990 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a  then the output.
379a0 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  ** parameters ar
379b0 65 20 73 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73  e set as follows
379c0 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a  :.**.** <pre>.**
379d0 20 20 20 20 20 64 61 74 61 20 74 79 70 65 3a 20       data type: 
379e0 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20  "INTEGER".**    
379f0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
37a00 6e 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a  nce: "BINARY".**
37a10 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30       not null: 0
37a20 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20  .**     primary 
37a30 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75  key: 1.**     au
37a40 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a  to increment: 0.
37a50 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a  ** </pre>)^.**.*
37a60 2a 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f  * ^(This functio
37a70 6e 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f  n may load one o
37a80 72 20 6d 6f 72 65 20 73 63 68 65 6d 61 73 20 66  r more schemas f
37a90 72 6f 6d 20 64 61 74 61 62 61 73 65 20 66 69 6c  rom database fil
37aa0 65 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72  es. If an.** err
37ab0 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
37ac0 20 74 68 69 73 20 70 72 6f 63 65 73 73 2c 20 6f   this process, o
37ad0 72 20 69 66 20 74 68 65 20 72 65 71 75 65 73 74  r if the request
37ae0 65 64 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75  ed table or colu
37af0 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20  mn.** cannot be 
37b00 66 6f 75 6e 64 2c 20 61 6e 20 5b 65 72 72 6f 72  found, an [error
37b10 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
37b20 65 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20  ed and an error 
37b30 6d 65 73 73 61 67 65 20 6c 65 66 74 0a 2a 2a 20  message left.** 
37b40 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  in the [database
37b50 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 6f   connection] (to
37b60 20 62 65 20 72 65 74 72 69 65 76 65 64 20 75 73   be retrieved us
37b70 69 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  ing sqlite3_errm
37b80 73 67 28 29 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  sg()).)^.**.** ^
37b90 54 68 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79  This API is only
37ba0 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68   available if th
37bb0 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f  e library was co
37bc0 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
37bd0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
37be0 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54  E_COLUMN_METADAT
37bf0 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f  A] C-preprocesso
37c00 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64  r symbol defined
37c10 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
37c20 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65  _table_column_me
37c30 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65  tadata(.  sqlite
37c40 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
37c50 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74        /* Connect
37c60 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ion handle */.  
37c70 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e  const char *zDbN
37c80 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44  ame,        /* D
37c90 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20  atabase name or 
37ca0 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  NULL */.  const 
37cb0 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65  char *zTableName
37cc0 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e  ,     /* Table n
37cd0 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ame */.  const c
37ce0 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65  har *zColumnName
37cf0 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e  ,    /* Column n
37d00 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f  ame */.  char co
37d10 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65  nst **pzDataType
37d20 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20  ,    /* OUTPUT: 
37d30 44 65 63 6c 61 72 65 64 20 64 61 74 61 20 74 79  Declared data ty
37d40 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e  pe */.  char con
37d50 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20  st **pzCollSeq, 
37d60 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43      /* OUTPUT: C
37d70 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
37d80 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20  e name */.  int 
37d90 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20  *pNotNull,      
37da0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55          /* OUTPU
37db0 54 3a 20 54 72 75 65 20 69 66 20 4e 4f 54 20 4e  T: True if NOT N
37dc0 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20 65  ULL constraint e
37dd0 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a  xists */.  int *
37de0 70 50 72 69 6d 61 72 79 4b 65 79 2c 20 20 20 20  pPrimaryKey,    
37df0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54         /* OUTPUT
37e00 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  : True if column
37e10 20 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20   part of PK */. 
37e20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20 20   int *pAutoinc  
37e30 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
37e40 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20  OUTPUT: True if 
37e50 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d 69  column is auto-i
37e60 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a  ncrement */.);..
37e70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37e80 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f  Load An Extensio
37e90 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  n.**.** ^This in
37ea0 74 65 72 66 61 63 65 20 6c 6f 61 64 73 20 61 6e  terface loads an
37eb0 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f   SQLite extensio
37ec0 6e 20 6c 69 62 72 61 72 79 20 66 72 6f 6d 20 74  n library from t
37ed0 68 65 20 6e 61 6d 65 64 20 66 69 6c 65 2e 0a 2a  he named file..*
37ee0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37ef0 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
37f00 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
37f10 65 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e  empts to load an
37f20 0a 2a 2a 20 53 51 4c 69 74 65 20 65 78 74 65 6e  .** SQLite exten
37f30 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e  sion library con
37f40 74 61 69 6e 65 64 20 69 6e 20 74 68 65 20 66 69  tained in the fi
37f50 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20  le zFile..**.** 
37f60 5e 54 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74  ^The entry point
37f70 20 69 73 20 7a 50 72 6f 63 2e 0a 2a 2a 20 5e 7a   is zProc..** ^z
37f80 50 72 6f 63 20 6d 61 79 20 62 65 20 30 2c 20 69  Proc may be 0, i
37f90 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  n which case the
37fa0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 65 6e 74   name of the ent
37fb0 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 64 65 66 61  ry point.** defa
37fc0 75 6c 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33  ults to "sqlite3
37fd0 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22  _extension_init"
37fe0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
37ff0 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
38000 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
38010 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
38020 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
38030 6e 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  nd [SQLITE_ERROR
38040 5d 20 69 66 20 73 6f 6d 65 74 68 69 6e 67 20 67  ] if something g
38050 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 49  oes wrong..** ^I
38060 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
38070 73 20 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 69  s and pzErrMsg i
38080 73 20 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74 68  s not 0, then th
38090 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  e.** [sqlite3_lo
380a0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
380b0 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20  interface shall 
380c0 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 66 69  attempt to.** fi
380d0 6c 6c 20 2a 70 7a 45 72 72 4d 73 67 20 77 69 74  ll *pzErrMsg wit
380e0 68 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  h error message 
380f0 74 65 78 74 20 73 74 6f 72 65 64 20 69 6e 20 6d  text stored in m
38100 65 6d 6f 72 79 0a 2a 2a 20 6f 62 74 61 69 6e 65  emory.** obtaine
38110 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
38120 6d 61 6c 6c 6f 63 28 29 5d 2e 20 54 68 65 20 63  malloc()]. The c
38130 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a  alling function.
38140 2a 2a 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74  ** should free t
38150 68 69 73 20 6d 65 6d 6f 72 79 20 62 79 20 63 61  his memory by ca
38160 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  lling [sqlite3_f
38170 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 45  ree()]..**.** ^E
38180 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67  xtension loading
38190 20 6d 75 73 74 20 62 65 20 65 6e 61 62 6c 65 64   must be enabled
381a0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
381b0 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65  e3_enable_load_e
381c0 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f  xtension()] prio
381d0 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69  r to calling thi
381e0 73 20 41 50 49 2c 0a 2a 2a 20 6f 74 68 65 72 77  s API,.** otherw
381f0 69 73 65 20 61 6e 20 65 72 72 6f 72 20 77 69 6c  ise an error wil
38200 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a  l be returned..*
38210 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
38220 65 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e [load_extensio
38230 6e 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  n() SQL function
38240 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
38250 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
38260 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
38270 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61            /* Loa
38280 64 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20  d the extension 
38290 69 6e 74 6f 20 74 68 69 73 20 64 61 74 61 62 61  into this databa
382a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f  se connection */
382b0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
382c0 46 69 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65  File,    /* Name
382d0 20 6f 66 20 74 68 65 20 73 68 61 72 65 64 20 6c   of the shared l
382e0 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ibrary containin
382f0 67 20 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20  g extension */. 
38300 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 72   const char *zPr
38310 6f 63 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 20  oc,    /* Entry 
38320 70 6f 69 6e 74 2e 20 20 44 65 72 69 76 65 64 20  point.  Derived 
38330 66 72 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 20  from zFile if 0 
38340 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72  */.  char **pzEr
38350 72 4d 73 67 20 20 20 20 20 20 20 2f 2a 20 50 75  rMsg       /* Pu
38360 74 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  t error message 
38370 68 65 72 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f  here if not 0 */
38380 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
38390 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44  REF: Enable Or D
383a0 69 73 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e  isable Extension
383b0 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e   Loading.**.** ^
383c0 53 6f 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65  So as not to ope
383d0 6e 20 73 65 63 75 72 69 74 79 20 68 6f 6c 65 73  n security holes
383e0 20 69 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69 63   in older applic
383f0 61 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 0a  ations that are.
38400 2a 2a 20 75 6e 70 72 65 70 61 72 65 64 20 74 6f  ** unprepared to
38410 20 64 65 61 6c 20 77 69 74 68 20 65 78 74 65 6e   deal with exten
38420 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e  sion loading, an
38430 64 20 61 73 20 61 20 6d 65 61 6e 73 20 6f 66 20  d as a means of 
38440 64 69 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74  disabling.** ext
38450 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77  ension loading w
38460 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20  hile evaluating 
38470 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c  user-entered SQL
38480 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  , the following 
38490 41 50 49 0a 2a 2a 20 69 73 20 70 72 6f 76 69 64  API.** is provid
384a0 65 64 20 74 6f 20 74 75 72 6e 20 74 68 65 20 5b  ed to turn the [
384b0 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
384c0 65 6e 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e  ension()] mechan
384d0 69 73 6d 20 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a  ism on and off..
384e0 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e  **.** ^Extension
384f0 20 6c 6f 61 64 69 6e 67 20 69 73 20 6f 66 66 20   loading is off 
38500 62 79 20 64 65 66 61 75 6c 74 2e 20 53 65 65 20  by default. See 
38510 74 69 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a  ticket #1863..**
38520 20 5e 43 61 6c 6c 20 74 68 65 20 73 71 6c 69 74   ^Call the sqlit
38530 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65  e3_enable_load_e
38540 78 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69  xtension() routi
38550 6e 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31  ne with onoff==1
38560 0a 2a 2a 20 74 6f 20 74 75 72 6e 20 65 78 74 65  .** to turn exte
38570 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e  nsion loading on
38580 20 61 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74   and call it wit
38590 68 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75  h onoff==0 to tu
385a0 72 6e 0a 2a 2a 20 69 74 20 62 61 63 6b 20 6f 66  rn.** it back of
385b0 66 20 61 67 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20  f again..*/.int 
385c0 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c  sqlite3_enable_l
385d0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71  oad_extension(sq
385e0 6c 69 74 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f  lite3 *db, int o
385f0 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  noff);../*.** CA
38600 50 49 33 52 45 46 3a 20 41 75 74 6f 6d 61 74 69  PI3REF: Automati
38610 63 61 6c 6c 79 20 4c 6f 61 64 20 53 74 61 74 69  cally Load Stati
38620 63 61 6c 6c 79 20 4c 69 6e 6b 65 64 20 45 78 74  cally Linked Ext
38630 65 6e 73 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54  ensions.**.** ^T
38640 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
38650 75 73 65 73 20 74 68 65 20 78 45 6e 74 72 79 50  uses the xEntryP
38660 6f 69 6e 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  oint() function 
38670 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f  to be invoked fo
38680 72 0a 2a 2a 20 65 61 63 68 20 6e 65 77 20 5b 64  r.** each new [d
38690 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
386a0 6f 6e 5d 20 74 68 61 74 20 69 73 20 63 72 65 61  on] that is crea
386b0 74 65 64 2e 20 20 54 68 65 20 69 64 65 61 20 68  ted.  The idea h
386c0 65 72 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 78  ere is that.** x
386d0 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 69 73 20  EntryPoint() is 
386e0 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20  the entry point 
386f0 66 6f 72 20 61 20 73 74 61 74 69 63 61 6c 6c 79  for a statically
38700 20 6c 69 6e 6b 65 64 20 53 51 4c 69 74 65 20 65   linked SQLite e
38710 78 74 65 6e 73 69 6f 6e 0a 2a 2a 20 74 68 61 74  xtension.** that
38720 20 69 73 20 74 6f 20 62 65 20 61 75 74 6f 6d 61   is to be automa
38730 74 69 63 61 6c 6c 79 20 6c 6f 61 64 65 64 20 69  tically loaded i
38740 6e 74 6f 20 61 6c 6c 20 6e 65 77 20 64 61 74 61  nto all new data
38750 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
38760 2e 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 6e 20 74  ..**.** ^(Even t
38770 68 6f 75 67 68 20 74 68 65 20 66 75 6e 63 74 69  hough the functi
38780 6f 6e 20 70 72 6f 74 6f 74 79 70 65 20 73 68 6f  on prototype sho
38790 77 73 20 74 68 61 74 20 78 45 6e 74 72 79 50 6f  ws that xEntryPo
387a0 69 6e 74 28 29 20 74 61 6b 65 73 0a 2a 2a 20 6e  int() takes.** n
387b0 6f 20 61 72 67 75 6d 65 6e 74 73 20 61 6e 64 20  o arguments and 
387c0 72 65 74 75 72 6e 73 20 76 6f 69 64 2c 20 53 51  returns void, SQ
387d0 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 78 45 6e  Lite invokes xEn
387e0 74 72 79 50 6f 69 6e 74 28 29 20 77 69 74 68 20  tryPoint() with 
387f0 74 68 72 65 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  three.** argumen
38800 74 73 20 61 6e 64 20 65 78 70 65 63 74 73 20 61  ts and expects a
38810 6e 64 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c  nd integer resul
38820 74 20 61 73 20 69 66 20 74 68 65 20 73 69 67 6e  t as if the sign
38830 61 74 75 72 65 20 6f 66 20 74 68 65 0a 2a 2a 20  ature of the.** 
38840 65 6e 74 72 79 20 70 6f 69 6e 74 20 77 68 65 72  entry point wher
38850 65 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  e as follows:.**
38860 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
38870 3c 70 72 65 3e 0a 2a 2a 20 26 6e 62 73 70 3b 20  <pre>.** &nbsp; 
38880 20 69 6e 74 20 78 45 6e 74 72 79 50 6f 69 6e 74   int xEntryPoint
38890 28 0a