/ Hex Artifact Content
Login

Artifact dcca940021f8f6643630fb7711bfd4e3fa002566:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
23f0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2400: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2410: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
2420: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2430: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
2440: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
2450: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2460: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
2470: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2480: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2490: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
24a0: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
24b0: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
24c0: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
24d0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
24e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24f0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2500: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2510: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
2520: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
2530: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
2540: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
2550: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
2560: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
2570: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2580: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2590: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
25a0: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
25b0: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
25c0: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
25d0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
25e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25f0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2600: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2610: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
2620: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
2630: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
2640: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2650: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
2660: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
2670: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2680: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2690: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26a0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26b0: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
26c0: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
26d0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
26e0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
26f0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2700: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2710: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
2720: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
2730: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2740: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
2750: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2760: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
2770: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2780: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2790: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
27a0: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
27b0: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
27c0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
27e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
27f0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2800: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2810: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
2820: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2830: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2840: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2850: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2860: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2870: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2890: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
28a0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
28b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
28c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
28d0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
28e0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2900: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2910: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2920: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2930: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2940: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2950: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2960: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2970: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2980: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2990: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
29a0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
29b0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
29c0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
29d0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
29e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
29f0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2a00: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2a10: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2a20: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
2a30: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2a40: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2a50: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
2a60: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
2a70: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
2a80: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
2a90: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
2aa0: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
2ab0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2ac0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
2ad0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ae0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2af0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2b00: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2b10: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2b20: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2b30: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2b40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2b50: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2b60: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2b70: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2b80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2b90: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2ba0: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2bb0: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2bc0: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2bd0: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2be0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2bf0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2c00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2c10: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2c20: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2c30: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2c40: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2c50: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e  ements.** and un
2c60: 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33  finished sqlite3
2c70: 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74  _backups, then t
2c80: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2c90: 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a  ection becomes.*
2ca0: 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a  * an unusable "z
2cb0: 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c  ombie" which wil
2cc0: 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2cd0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77  be deallocated w
2ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20  hen the.** last 
2cf0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d00: 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20  nt is finalized 
2d10: 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  or the last sqli
2d20: 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a  te3_backup is.**
2d30: 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20   finished.  The 
2d40: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2d50: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2d60: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
2d70: 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61   with.** host la
2d80: 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65  nguages that are
2d90: 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74   garbage collect
2da0: 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68  ed, and where th
2db0: 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68  e order in which
2dc0: 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20  .** destructors 
2dd0: 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72  are called is ar
2de0: 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41  bitrary..**.** A
2df0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
2e00: 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ld [sqlite3_fina
2e10: 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d  lize | finalize]
2e20: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73   all [prepared s
2e30: 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b  tatements],.** [
2e40: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
2e50: 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20  se | close] all 
2e60: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20  [BLOB handles], 
2e70: 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
2e80: 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c  _backup_finish |
2e90: 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71   finish] all [sq
2ea0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
2eb0: 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64  jects associated
2ec0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71  .** with the [sq
2ed0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72  lite3] object pr
2ee0: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  ior to attemptin
2ef0: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f  g to close the o
2f00: 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73  bject.  ^If.** s
2f10: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2f20: 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61  ) is called on a
2f30: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2f40: 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c  ction] that stil
2f50: 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e  l has.** outstan
2f60: 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73  ding [prepared s
2f70: 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f  tatements], [BLO
2f80: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f  B handles], and/
2f90: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  or.** [sqlite3_b
2fa0: 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74  ackup] objects t
2fb0: 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20 53  hen it returns S
2fc0: 51 4c 49 54 45 5f 4f 4b 20 62 75 74 20 74 68 65  QLITE_OK but the
2fd0: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
2fe0: 20 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73   of resources is
2ff0: 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
3000: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74  all [prepared st
3010: 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42  atements], [BLOB
3020: 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e   handles],.** an
3030: 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  d [sqlite3_backu
3040: 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61  p] objects are a
3050: 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  lso destroyed..*
3060: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c  *.** ^If an [sql
3070: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20  ite3] object is 
3080: 64 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20  destroyed while 
3090: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
30a0: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72   open,.** the tr
30b0: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74  ansaction is aut
30c0: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
30d0: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
30e0: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e C parameter to
30f0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
3100: 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  C)] and [sqlite3
3110: 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a  _close_v2(C)].**
3120: 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
3130: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
3140: 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  r or an [sqlite3
3150: 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72  ] object pointer
3160: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3170: 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  m [sqlite3_open(
3180: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
3190: 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
31a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
31b0: 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69  ], and not previ
31c0: 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a  ously closed..**
31d0: 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
31e0: 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c  3_close() or sql
31f0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
3200: 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
3210: 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ter.** argument 
3220: 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
3230: 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  -op..*/.int sqli
3240: 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  te3_close(sqlite
3250: 33 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  3*);.int sqlite3
3260: 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65  _close_v2(sqlite
3270: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  3*);../*.** The 
3280: 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62  type for a callb
3290: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ack function..**
32a0: 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20   This is legacy 
32b0: 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20  and deprecated. 
32c0: 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20   It is included 
32d0: 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a  for historical.*
32e0: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
32f0: 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d  and is not docum
3300: 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65  ented..*/.typede
3310: 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f  f int (*sqlite3_
3320: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
3330: 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72  int,char**, char
3340: 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  **);../*.** CAPI
3350: 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51  3REF: One-Step Q
3360: 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49  uery Execution I
3370: 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54  nterface.**.** T
3380: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3390: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61  ) interface is a
33a0: 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61   convenience wra
33b0: 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
33c0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
33d0: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
33e0: 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71  step()], and [sq
33f0: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
3400: 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77  ],.** that allow
3410: 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  s an application
3420: 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65   to run multiple
3430: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53   statements of S
3440: 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61  QL.** without ha
3450: 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f  ving to use a lo
3460: 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a  t of C code. .**
3470: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
3480: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
3490: 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d  e runs zero or m
34a0: 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ore UTF-8 encode
34b0: 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  d,.** semicolon-
34c0: 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 61  separate SQL sta
34d0: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69  tements passed i
34e0: 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75  nto its 2nd argu
34f0: 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20  ment,.** in the 
3500: 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b  context of the [
3510: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3520: 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61  ion] passed in a
3530: 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67  s its 1st.** arg
3540: 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20  ument.  ^If the 
3550: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
3560: 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 67  n of the 3rd arg
3570: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69  ument to.** sqli
3580: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
3590: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20  t NULL, then it 
35a0: 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65  is invoked for e
35b0: 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a  ach result row.*
35c0: 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20  * coming out of 
35d0: 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 51  the evaluated SQ
35e0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e  L statements.  ^
35f0: 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74  The 4th argument
3600: 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65   to.** sqlite3_e
3610: 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65 64  xec() is relayed
3620: 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
3630: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  1st argument of 
3640: 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  each.** callback
3650: 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49   invocation.  ^I
3660: 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70  f the callback p
3670: 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
3680: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e  3_exec().** is N
3690: 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c  ULL, then no cal
36a0: 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e  lback is ever in
36b0: 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74  voked and result
36c0: 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e   rows are.** ign
36d0: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ored..**.** ^If 
36e0: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
36f0: 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67  while evaluating
3700: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
3710: 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a  nts passed into.
3720: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3730: 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f  ), then executio
3740: 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
3750: 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73   statement stops
3760: 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65   and.** subseque
3770: 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  nt statements ar
3780: 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20  e skipped.  ^If 
3790: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
37a0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
37b0: 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  c().** is not NU
37c0: 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f  LL then any erro
37d0: 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 69  r message is wri
37e0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
37f0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3800: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
3810: 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20  c()] and passed 
3820: 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65  back through the
3830: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a   5th parameter..
3840: 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f  ** To avoid memo
3850: 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70  ry leaks, the ap
3860: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
3870: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
3880: 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65  _free()].** on e
3890: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
38a0: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74 68  ings returned th
38b0: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
38c0: 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66  rameter of.** of
38d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
38e0: 61 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20  after the error 
38f0: 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
3900: 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64  s no longer need
3910: 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35  ed..** ^If the 5
3920: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
3930: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3940: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e  s not NULL and n
3950: 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75  o errors.** occu
3960: 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  r, then sqlite3_
3970: 65 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20  exec() sets the 
3980: 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35  pointer in its 5
3990: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
39a0: 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72  ** NULL before r
39b0: 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
39c0: 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65  ^If an sqlite3_e
39d0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72  xec() callback r
39e0: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
39f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3a00: 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  c().** routine r
3a10: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42  eturns SQLITE_AB
3a20: 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f  ORT without invo
3a30: 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63  king the callbac
3a40: 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77  k again and.** w
3a50: 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61  ithout running a
3a60: 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51  ny subsequent SQ
3a70: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
3a80: 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67  .** ^The 2nd arg
3a90: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
3aa0: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
3ab0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73  back function is
3ac0: 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
3ad0: 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
3ae0: 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33   result.  ^The 3
3af0: 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rd argument to t
3b00: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3b10: 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73  ).** callback is
3b20: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3b30: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3b40: 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20   obtained as if 
3b50: 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
3b60: 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
3b70: 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f   one for each co
3b80: 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c  lumn.  ^If an el
3b90: 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65  ement of a.** re
3ba0: 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c  sult row is NULL
3bb0: 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   then the corres
3bc0: 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70  ponding string p
3bd0: 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a  ointer for the.*
3be0: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  * sqlite3_exec()
3bf0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e   callback is a N
3c00: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54  ULL pointer.  ^T
3c10: 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20  he 4th argument 
3c20: 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  to the.** sqlite
3c30: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3c40: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  k is an array of
3c50: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
3c60: 69 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a  ings where each.
3c70: 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65  ** entry represe
3c80: 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  nts the name of 
3c90: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65  corresponding re
3ca0: 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f  sult column as o
3cb0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3cc0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
3cd0: 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  name()]..**.** ^
3ce0: 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  If the 2nd param
3cf0: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
3d00: 65 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c  exec() is a NULL
3d10: 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e   pointer, a poin
3d20: 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70  ter.** to an emp
3d30: 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20  ty string, or a 
3d40: 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e  pointer that con
3d50: 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65  tains only white
3d60: 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a  space and/or .**
3d70: 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74   SQL comments, t
3d80: 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65  hen no SQL state
3d90: 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61  ments are evalua
3da0: 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61  ted and the data
3db0: 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63  base.** is not c
3dc0: 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65  hanged..**.** Re
3dd0: 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a  strictions:.**.*
3de0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
3df0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e00: 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20  ust insure that 
3e10: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
3e20: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3e30: 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61  c().**      is a
3e40: 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20   valid and open 
3e50: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3e60: 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  tion]..** <li> T
3e70: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e80: 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64  ust not close [d
3e90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3ea0: 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
3eb0: 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73 74  .**      the 1st
3ec0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3ed0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69  lite3_exec() whi
3ee0: 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  le sqlite3_exec(
3ef0: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  ) is running..**
3f00: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3f10: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d  ation must not m
3f20: 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73 74  odify the SQL st
3f30: 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73  atement text pas
3f40: 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20  sed into.**     
3f50: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
3f60: 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78  er of sqlite3_ex
3f70: 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74  ec() while sqlit
3f80: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e  e3_exec() is run
3f90: 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  ning..** </ul>.*
3fa0: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
3fb0: 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ec(.  sqlite3*, 
3fc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fe0: 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
3ff0: 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
4000: 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20  char *sql,      
4010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4020: 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
4030: 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
4040: 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29   int (*callback)
4050: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
4060: 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43  *,char**),  /* C
4070: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
4080: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20   */.  void *,   
4090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74   /* 1st argument
40c0: 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a   to callback */.
40d0: 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20    char **errmsg 
40e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
4100: 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
4110: 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  n here */.);../*
4120: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
4130: 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45  sult Codes.** KE
4140: 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f  YWORDS: SQLITE_O
4150: 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b  K {error code} {
4160: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
4170: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
4180: 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20  t code} {result 
4190: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e  codes}.**.** Man
41a0: 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f  y SQLite functio
41b0: 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74  ns return an int
41c0: 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65  eger result code
41d0: 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68   from the set sh
41e0: 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f  own.** here in o
41f0: 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65  rder to indicate
4200: 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c   success or fail
4210: 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65  ure..**.** New e
4220: 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62  rror codes may b
4230: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
4240: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
4250: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  Lite..**.** See 
4260: 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f  also: [SQLITE_IO
4270: 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e  ERR_READ | exten
4280: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4290: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  ],.** [sqlite3_v
42a0: 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28  tab_on_conflict(
42b0: 29 5d 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42  )] [SQLITE_ROLLB
42c0: 41 43 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64  ACK | result cod
42d0: 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  es]..*/.#define 
42e0: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
42f0: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
4300: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
4310: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
4320: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
4330: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
4340: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
4350: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
4360: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
4370: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4380: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
4390: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
43a0: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
43b0: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
43c0: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
43d0: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
43e0: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
43f0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
4400: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
4410: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
4420: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
4430: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
4440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4450: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
4460: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
4470: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
4480: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4490: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
44a0: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
44b0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
44c0: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
44d0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
44e0: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
44f0: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
4500: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4510: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
4520: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
4530: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
4540: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
4550: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
4560: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
4570: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
4580: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
4590: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
45a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
45b0: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
45c0: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
45d0: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
45e0: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
45f0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
4600: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
4610: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
4620: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
4630: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4640: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
4650: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20  12   /* Unknown 
4660: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65  opcode in sqlite
4670: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
4680: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4690: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
46a0: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
46b0: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
46c0: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
46d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
46e0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
46f0: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
4700: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
4710: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4720: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
4730: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61  OL    15   /* Da
4740: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74  tabase lock prot
4750: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64  ocol error */.#d
4760: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50  efine SQLITE_EMP
4770: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a  TY       16   /*
4780: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70   Database is emp
4790: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ty */.#define SQ
47a0: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20  LITE_SCHEMA     
47b0: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74   17   /* The dat
47c0: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
47d0: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nged */.#define 
47e0: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20  SQLITE_TOOBIG   
47f0: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e     18   /* Strin
4800: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64  g or BLOB exceed
4810: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a  s size limit */.
4820: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
4830: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
4840: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
4850: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
4860: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tion */.#define 
4870: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20  SQLITE_MISMATCH 
4880: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20     20   /* Data 
4890: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f  type mismatch */
48a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
48b0: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20  MISUSE      21  
48c0: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64   /* Library used
48d0: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a   incorrectly */.
48e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
48f0: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20  OLFS       22   
4900: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75  /* Uses OS featu
4910: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  res not supporte
4920: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65  d on host */.#de
4930: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
4940: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
4950: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65  Authorization de
4960: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4970: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20  SQLITE_FORMAT   
4980: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c     24   /* Auxil
4990: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f  iary database fo
49a0: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64  rmat error */.#d
49b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e  efine SQLITE_RAN
49c0: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a  GE       25   /*
49d0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
49e0: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f  o sqlite3_bind o
49f0: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23  ut of range */.#
4a00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4a10: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f  TADB      26   /
4a20: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68  * File opened th
4a30: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  at is not a data
4a40: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4a50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
4a60: 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20  CE      27   /* 
4a70: 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72  Notifications fr
4a80: 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  om sqlite3_log()
4a90: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4aa0: 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32  TE_WARNING     2
4ab0: 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20  8   /* Warnings 
4ac0: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67  from sqlite3_log
4ad0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
4ae0: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20  LITE_ROW        
4af0: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33   100  /* sqlite3
4b00: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74  _step() has anot
4b10: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f  her row ready */
4b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b30: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20  DONE        101 
4b40: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
4b50: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  () has finished 
4b60: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20  executing */./* 
4b70: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  end-of-error-cod
4b80: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  es */../*.** CAP
4b90: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20  I3REF: Extended 
4ba0: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4bb0: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
4bc0: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20  ded error code} 
4bd0: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
4be0: 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  codes}.** KEYWOR
4bf0: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4c00: 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 65  sult code} {exte
4c10: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4c20: 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20  s}.**.** In its 
4c30: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
4c40: 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50  ation, SQLite AP
4c50: 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  I routines retur
4c60: 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65  n one of 26 inte
4c70: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ger.** [SQLITE_O
4c80: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
4c90: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70  ].  However, exp
4ca0: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77  erience has show
4cb0: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a  n that many of.*
4cc0: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63  * these result c
4cd0: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61  odes are too coa
4ce0: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68  rse-grained.  Th
4cf0: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64  ey do not provid
4d00: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66  e as.** much inf
4d10: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70  ormation about p
4d20: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72  roblems as progr
4d30: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b  ammers might lik
4d40: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74  e.  In an effort
4d50: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74   to.** address t
4d60: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69  his, newer versi
4d70: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76  ons of SQLite (v
4d80: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64  ersion 3.3.8 and
4d90: 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a   later) include.
4da0: 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61  ** support for a
4db0: 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74  dditional result
4dc0: 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76   codes that prov
4dd0: 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65  ide more detaile
4de0: 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  d information.**
4df0: 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54   about errors. T
4e00: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
4e10: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61  lt codes are ena
4e20: 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
4e30: 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74  .** on a per dat
4e40: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
4e50: 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65   basis using the
4e60: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
4e70: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
4e80: 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a  es()] API..**.**
4e90: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61   Some of the ava
4ea0: 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20  ilable extended 
4eb0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4ec0: 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a   listed here..**
4ed0: 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20   One may expect 
4ee0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78  the number of ex
4ef0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4f00: 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61  des will be expa
4f10: 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e  nd.** over time.
4f20: 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
4f30: 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 65  uses extended re
4f40: 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c  sult codes shoul
4f50: 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73  d expect.** to s
4f60: 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f  ee new result co
4f70: 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65  des in future re
4f80: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
4f90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
4fa0: 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64  TE_OK result cod
4fb0: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20  e will never be 
4fc0: 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69  extended.  It wi
4fd0: 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ll always.** be 
4fe0: 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f  exactly zero..*/
4ff0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5000: 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20  IOERR_READ      
5010: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5020: 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a  IOERR | (1<<8)).
5030: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5040: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
5050: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5060: 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23  OERR | (2<<8)).#
5070: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5080: 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20  ERR_WRITE       
5090: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
50a0: 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  ERR | (3<<8)).#d
50b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
50c0: 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20  RR_FSYNC        
50d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
50e0: 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  RR | (4<<8)).#de
50f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5100: 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20  R_DIR_FSYNC     
5110: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5120: 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66  R | (5<<8)).#def
5130: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5140: 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 20  _TRUNCATE       
5150: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5160: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69   | (6<<8)).#defi
5170: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5180: 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20 20  FSTAT           
5190: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
51a0: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (7<<8)).#defin
51b0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55  e SQLITE_IOERR_U
51c0: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  NLOCK           
51d0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
51e0: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
51f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44   SQLITE_IOERR_RD
5200: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
5210: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5220: 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (9<<8)).#define 
5230: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c  SQLITE_IOERR_DEL
5240: 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 28  ETE            (
5250: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5260: 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  10<<8)).#define 
5270: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
5280: 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 28  CKED           (
5290: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
52a0: 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  11<<8)).#define 
52b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d  SQLITE_IOERR_NOM
52c0: 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 28  EM             (
52d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
52e0: 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  12<<8)).#define 
52f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43  SQLITE_IOERR_ACC
5300: 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20 28  ESS            (
5310: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5320: 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  13<<8)).#define 
5330: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45  SQLITE_IOERR_CHE
5340: 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28  CKRESERVEDLOCK (
5350: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5360: 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  14<<8)).#define 
5370: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43  SQLITE_IOERR_LOC
5380: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
5390: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
53a0: 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  15<<8)).#define 
53b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f  SQLITE_IOERR_CLO
53c0: 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28  SE             (
53d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
53e0: 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  16<<8)).#define 
53f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
5400: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28  _CLOSE         (
5410: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5420: 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  17<<8)).#define 
5430: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5440: 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20 28  OPEN           (
5450: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5460: 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  18<<8)).#define 
5470: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5480: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 28  SIZE           (
5490: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
54a0: 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  19<<8)).#define 
54b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
54c0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 28  LOCK           (
54d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
54e0: 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  20<<8)).#define 
54f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5500: 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20 28  MAP            (
5510: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5520: 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  21<<8)).#define 
5530: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45  SQLITE_IOERR_SEE
5540: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
5550: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5560: 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  22<<8)).#define 
5570: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c  SQLITE_IOERR_DEL
5580: 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28  ETE_NOENT      (
5590: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
55a0: 32 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  23<<8)).#define 
55b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41  SQLITE_IOERR_MMA
55c0: 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  P              (
55d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
55e0: 32 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  24<<8)).#define 
55f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45 54  SQLITE_IOERR_GET
5600: 54 45 4d 50 50 41 54 48 20 20 20 20 20 20 20 28  TEMPPATH       (
5610: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5620: 32 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  25<<8)).#define 
5630: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48  SQLITE_LOCKED_SH
5640: 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 28  AREDCACHE      (
5650: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20  SQLITE_LOCKED | 
5660: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5670: 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43   SQLITE_BUSY_REC
5680: 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20 20  OVERY           
5690: 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c  (SQLITE_BUSY   |
56a0: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
56b0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e  e SQLITE_BUSY_SN
56c0: 41 50 53 48 4f 54 20 20 20 20 20 20 20 20 20 20  APSHOT          
56d0: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20   (SQLITE_BUSY   
56e0: 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69  |  (2<<8)).#defi
56f0: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5700: 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20  EN_NOTEMPDIR    
5710: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5720: 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  EN | (1<<8)).#de
5730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
5740: 4f 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20  OPEN_ISDIR      
5750: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54      (SQLITE_CANT
5760: 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23  OPEN | (2<<8)).#
5770: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5780: 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20  NTOPEN_FULLPATH 
5790: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
57a0: 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29  NTOPEN | (3<<8))
57b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
57c0: 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20  CORRUPT_VTAB    
57d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
57e0: 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29  CORRUPT | (1<<8)
57f0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5800: 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45  _READONLY_RECOVE
5810: 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  RY       (SQLITE
5820: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c  _READONLY | (1<<
5830: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5840: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54  TE_READONLY_CANT
5850: 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49  LOCK       (SQLI
5860: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32  TE_READONLY | (2
5870: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5880: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f  LITE_READONLY_RO
5890: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51  LLBACK       (SQ
58a0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
58b0: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
58c0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c  SQLITE_ABORT_ROL
58d0: 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28  LBACK          (
58e0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28  SQLITE_ABORT | (
58f0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5900: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5910: 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53  _CHECK        (S
5920: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5930: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5940: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5950: 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20  AINT_COMMITHOOK 
5960: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5970: 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23  AINT | (2<<8)).#
5980: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5990: 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e  NSTRAINT_FOREIGN
59a0: 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f  KEY   (SQLITE_CO
59b0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38  NSTRAINT | (3<<8
59c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
59d0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e  E_CONSTRAINT_FUN
59e0: 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54  CTION     (SQLIT
59f0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5a00: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5a10: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5a20: 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53  _NOTNULL      (S
5a30: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5a40: 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69   | (5<<8)).#defi
5a50: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5a60: 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20  AINT_PRIMARYKEY 
5a70: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5a80: 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23  AINT | (6<<8)).#
5a90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5aa0: 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52  NSTRAINT_TRIGGER
5ab0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5ac0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38  NSTRAINT | (7<<8
5ad0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5ae0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49  E_CONSTRAINT_UNI
5af0: 51 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54  QUE       (SQLIT
5b00: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5b10: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  8<<8)).#define S
5b20: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5b30: 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53  _VTAB         (S
5b40: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5b50: 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69   | (9<<8)).#defi
5b60: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45  ne SQLITE_NOTICE
5b70: 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20  _RECOVER_WAL    
5b80: 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45    (SQLITE_NOTICE
5b90: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5ba0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45  ne SQLITE_NOTICE
5bb0: 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43  _RECOVER_ROLLBAC
5bc0: 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45  K (SQLITE_NOTICE
5bd0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5be0: 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e  ne SQLITE_WARNIN
5bf0: 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 20 20  G_AUTOINDEX     
5c00: 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e    (SQLITE_WARNIN
5c10: 47 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a  G | (1<<8))../*.
5c20: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
5c30: 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e  gs For File Open
5c40: 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a   Operations.**.*
5c50: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75  * These bit valu
5c60: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  es are intended 
5c70: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a  for use in the.*
5c80: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  * 3rd parameter 
5c90: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5ca0: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
5cb0: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74  face and.** in t
5cc0: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
5cd0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5ce0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
5cf0: 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  od..*/.#define S
5d00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
5d10: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30  NLY         0x00
5d20: 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f  000001  /* Ok fo
5d30: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5d40: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5d50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
5d60: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30  RITE        0x00
5d70: 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f  000002  /* Ok fo
5d80: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5d90: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5da0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
5db0: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  E           0x00
5dc0: 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f  000004  /* Ok fo
5dd0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5de0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5df0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
5e00: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30  EONCLOSE    0x00
5e10: 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f  000008  /* VFS o
5e20: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5e30: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
5e40: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30  SIVE        0x00
5e50: 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f  000010  /* VFS o
5e60: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5e70: 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50  QLITE_OPEN_AUTOP
5e80: 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30  ROXY        0x00
5e90: 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f  000020  /* VFS o
5ea0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5eb0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20  QLITE_OPEN_URI  
5ec0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5ed0: 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f  000040  /* Ok fo
5ee0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5ef0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5f00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52  QLITE_OPEN_MEMOR
5f10: 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  Y           0x00
5f20: 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f  000080  /* Ok fo
5f30: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5f40: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5f50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
5f60: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
5f70: 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f  000100  /* VFS o
5f80: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5f90: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
5fa0: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
5fb0: 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f  000200  /* VFS o
5fc0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5fd0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
5fe0: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30  IENT_DB     0x00
5ff0: 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f  000400  /* VFS o
6000: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6010: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
6020: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
6030: 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f  000800  /* VFS o
6040: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6050: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
6060: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
6070: 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  001000  /* VFS o
6080: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6090: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
60a0: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30  URNAL       0x00
60b0: 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  002000  /* VFS o
60c0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
60d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
60e0: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30  R_JOURNAL   0x00
60f0: 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  004000  /* VFS o
6100: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6110: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
6120: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30  EX          0x00
6130: 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  008000  /* Ok fo
6140: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6150: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6160: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
6170: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30  UTEX        0x00
6180: 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  010000  /* Ok fo
6190: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
61a0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
61b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
61c0: 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30  DCACHE      0x00
61d0: 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  020000  /* Ok fo
61e0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
61f0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6200: 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
6210: 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30  TECACHE     0x00
6220: 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  040000  /* Ok fo
6230: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6240: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6250: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20  QLITE_OPEN_WAL  
6260: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6270: 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  080000  /* VFS o
6280: 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72  nly */../* Reser
6290: 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20  ved:            
62a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
62b0: 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a  0F00000 */../*.*
62c0: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
62d0: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
62e0: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
62f0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
6300: 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ics method of th
6310: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
6320: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74  thods].** object
6330: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
6340: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76  ger which is a v
6350: 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a  ector of these.*
6360: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70  * bit values exp
6370: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72  ressing I/O char
6380: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74  acteristics of t
6390: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a  he mass storage.
63a0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68  ** device that h
63b0: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68  olds the file th
63c0: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
63d0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72  io_methods].** r
63e0: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20  efers to..**.** 
63f0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6400: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
6410: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
6420: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
6430: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
6440: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6450: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
6460: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
6470: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
6480: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
6490: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
64a0: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
64b0: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
64c0: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
64d0: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
64e0: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
64f0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6500: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
6510: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
6520: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
6530: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
6540: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
6550: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
6560: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
6570: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
6580: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
6590: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
65a0: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
65b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
65c0: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
65d0: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
65e0: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
65f0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
6600: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
6610: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
6620: 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49  ite().  The SQLI
6630: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
6640: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f  FE_OVERWRITE pro
6650: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6660: 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74  .** after reboot
6670: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61   following a cra
6680: 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73  sh or power loss
6690: 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73  , the only bytes
66a0: 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68   in a.** file th
66b0: 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20  at were written 
66c0: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
66d0: 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68  on level might h
66e0: 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61  ave changed.** a
66f0: 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74  nd that adjacent
6700: 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74   bytes, even byt
6710: 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  es within the sa
6720: 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a  me sector are.**
6730: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
6740: 65 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a  e unchanged..*/.
6750: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6760: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20  OCAP_ATOMIC     
6770: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6780: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
6790: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
67a0: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20  IC512           
67b0: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
67c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
67d0: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20  AP_ATOMIC1K     
67e0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
67f0: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
6800: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6810: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
6820: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
6830: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6840: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
6850: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6860: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
6870: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
6880: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6890: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e  x00000020.#defin
68a0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
68b0: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20  TOMIC16K        
68c0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
68d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
68e0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
68f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6900: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
6910: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6920: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20  MIC64K          
6930: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
6940: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6950: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
6960: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6970: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
6980: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
6990: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20  NTIAL           
69a0: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65    0x00000400.#de
69b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
69c0: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
69d0: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30  EN_OPEN  0x00000
69e0: 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  800.#define SQLI
69f0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
6a00: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
6a10: 30 78 30 30 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a  0x00001000../*.*
6a20: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
6a30: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
6a40: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
6a50: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
6a60: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
6a70: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
6a80: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
6a90: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
6aa0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
6ab0: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
6ac0: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
6ad0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
6ae0: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
6af0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
6b00: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
6b10: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6b20: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
6b30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6b40: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
6b50: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
6b60: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
6b70: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
6b80: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
6b90: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
6ba0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
6bb0: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
6bc0: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
6bd0: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
6be0: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
6bf0: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
6c00: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
6c10: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
6c20: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
6c30: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
6c40: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
6c50: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
6c60: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
6c70: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
6c80: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
6c90: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
6ca0: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
6cb0: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
6cc0: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
6cd0: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
6ce0: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
6cf0: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
6d00: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
6d10: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
6d20: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
6d30: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
6d40: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
6d50: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
6d60: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
6d70: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
6d80: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
6d90: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
6da0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
6db0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
6dc0: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
6dd0: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
6de0: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a   of fsync()..**.
6df0: 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73  ** Do not confus
6e00: 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  e the SQLITE_SYN
6e10: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
6e20: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c  ITE_SYNC_FULL fl
6e30: 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ags.** with the 
6e40: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
6e50: 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20  ous]=NORMAL and 
6e60: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
6e70: 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74  ous]=FULL.** set
6e80: 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e  tings.  The [syn
6e90: 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d  chronous pragma]
6ea0: 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e   determines when
6eb0: 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a   calls to the.**
6ec0: 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f   xSync VFS metho
6ed0: 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c  d occur and appl
6ee0: 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63  ies uniformly ac
6ef0: 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72  ross all platfor
6f00: 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  ms..** The SQLIT
6f10: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
6f20: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
6f30: 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69  LL flags determi
6f40: 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65  ne how.** energe
6f50: 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20  tic or rigorous 
6f60: 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20  or forceful the 
6f70: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20  sync operations 
6f80: 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20  are and.** only 
6f90: 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63  make a differenc
6fa0: 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72  e on Mac OSX for
6fb0: 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c   the default SQL
6fc0: 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68  ite code..** (Th
6fd0: 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d  ird-party VFS im
6fe0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69  plementations mi
6ff0: 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68  ght also make th
7000: 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a  e distinction.**
7010: 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f   between SQLITE_
7020: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
7030: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7040: 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a  , but among the.
7050: 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ** operating sys
7060: 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75  tems natively su
7070: 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
7080: 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a  e, only Mac OSX.
7090: 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74  ** cares about t
70a0: 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a  he difference.).
70b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
70c0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20  E_SYNC_NORMAL   
70d0: 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65       0x00002.#de
70e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
70f0: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30  _FULL          0
7100: 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53  x00003.#define S
7110: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
7120: 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30  NLY      0x00010
7130: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
7140: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f  : OS Interface O
7150: 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a  pen File Handle.
7160: 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65  **.** An [sqlite
7170: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72  3_file] object r
7180: 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65  epresents an ope
7190: 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a  n file in the .*
71a0: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  * [sqlite3_vfs |
71b0: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
71c0: 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61  yer].  Individua
71d0: 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a  l OS interface.*
71e0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
71f0: 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74  s will.** want t
7200: 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20  o subclass this 
7210: 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64  object by append
7220: 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ing additional f
7230: 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ields.** for the
7240: 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65  ir own use.  The
7250: 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20   pMethods entry 
7260: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
7270: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
7280: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
7290: 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d  t that defines m
72a0: 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f  ethods for perfo
72b0: 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65  rming.** I/O ope
72c0: 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f  rations on the o
72d0: 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70  pen file..*/.typ
72e0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
72f0: 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33  te3_file sqlite3
7300: 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71  _file;.struct sq
7310: 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63  lite3_file {.  c
7320: 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69  onst struct sqli
7330: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a  te3_io_methods *
7340: 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65  pMethods;  /* Me
7350: 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65  thods for an ope
7360: 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  n file */.};../*
7370: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
7380: 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20   Interface File 
7390: 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20  Virtual Methods 
73a0: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65  Object.**.** Eve
73b0: 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62  ry file opened b
73c0: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  y the [sqlite3_v
73d0: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64  fs.xOpen] method
73e0: 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a   populates an.**
73f0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
7400: 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65  object (or, more
7410: 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62   commonly, a sub
7420: 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20  class of the.** 
7430: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
7440: 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f  bject) with a po
7450: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
7460: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
7470: 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ect..** This obj
7480: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
7490: 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20  methods used to 
74a0: 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
74b0: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67  operations.** ag
74c0: 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66  ainst the open f
74d0: 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20  ile represented 
74e0: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
74f0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  file] object..**
7500: 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69  .** If the [sqli
7510: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d  te3_vfs.xOpen] m
7520: 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73  ethod sets the s
7530: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
7540: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a  hods element .**
7550: 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70   to a non-NULL p
7560: 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65  ointer, then the
7570: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
7580: 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f  ods.xClose metho
7590: 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f  d.** may be invo
75a0: 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20  ked even if the 
75b0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
75c0: 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61  en] reported tha
75d0: 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68  t it failed.  Th
75e0: 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f  e.** only way to
75f0: 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20   prevent a call 
7600: 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77  to xClose follow
7610: 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71  ing a failed [sq
7620: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7630: 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b  .** is for the [
7640: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7650: 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71  n] to set the sq
7660: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
7670: 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74  ods element.** t
7680: 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  o NULL..**.** Th
7690: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
76a0: 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65   to xSync may be
76b0: 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
76c0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a  SYNC_NORMAL] or.
76d0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ** [SQLITE_SYNC_
76e0: 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73  FULL].  The firs
76f0: 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20  t choice is the 
7700: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a  normal fsync()..
7710: 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68  ** The second ch
7720: 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53  oice is a Mac OS
7730: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
7740: 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  c.  The [SQLITE_
7750: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a  SYNC_DATAONLY].*
7760: 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52  * flag may be OR
7770: 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74  ed in to indicat
7780: 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20  e that only the 
7790: 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65  data of the file
77a0: 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20  .** and not its 
77b0: 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62  inode needs to b
77c0: 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20  e synced..**.** 
77d0: 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  The integer valu
77e0: 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e  es to xLock() an
77f0: 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20  d xUnlock() are 
7800: 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a  one of.** <ul>.*
7810: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7820: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c  OCK_NONE],.** <l
7830: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7840: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e  SHARED],.** <li>
7850: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
7860: 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e  SERVED],.** <li>
7870: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
7880: 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c  NDING], or.** <l
7890: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
78a0: 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c  EXCLUSIVE]..** <
78b0: 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20  /ul>.** xLock() 
78c0: 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  increases the lo
78d0: 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65  ck. xUnlock() de
78e0: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
78f0: 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52  ..** The xCheckR
7900: 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65  eservedLock() me
7910: 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74  thod checks whet
7920: 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65  her any database
7930: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20   connection,.** 
7940: 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70  either in this p
7950: 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d  rocess or in som
7960: 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c  e other process,
7970: 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45   is holding a RE
7980: 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49  SERVED,.** PENDI
7990: 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45  NG, or EXCLUSIVE
79a0: 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c   lock on the fil
79b0: 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74  e.  It returns t
79c0: 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61  rue.** if such a
79d0: 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64   lock exists and
79e0: 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65   false otherwise
79f0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c  ..**.** The xFil
7a00: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f  eControl() metho
7a10: 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69  d is a generic i
7a20: 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c  nterface that al
7a30: 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56  lows custom.** V
7a40: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
7a50: 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63  ns to directly c
7a60: 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66  ontrol an open f
7a70: 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ile using the.**
7a80: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
7a90: 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66  ontrol()] interf
7aa0: 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ace.  The second
7ab0: 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69   "op" argument i
7ac0: 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20  s an.** integer 
7ad0: 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69  opcode.  The thi
7ae0: 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  rd argument is a
7af0: 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72   generic pointer
7b00: 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20   intended to.** 
7b10: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63  point to a struc
7b20: 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f  ture that may co
7b30: 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20  ntain arguments 
7b40: 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63  or space in whic
7b50: 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65  h to.** write re
7b60: 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f  turn values.  Po
7b70: 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72  tential uses for
7b80: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20   xFileControl() 
7b90: 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63  might be.** func
7ba0: 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20  tions to enable 
7bb0: 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77  blocking locks w
7bc0: 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f  ith timeouts, to
7bd0: 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c   change the.** l
7be0: 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20  ocking strategy 
7bf0: 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20  (for example to 
7c00: 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63  use dot-file loc
7c10: 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a  ks), to inquire.
7c20: 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61  ** about the sta
7c30: 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f  tus of a lock, o
7c40: 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65  r to break stale
7c50: 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c   locks.  The SQL
7c60: 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65  ite.** core rese
7c70: 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73  rves all opcodes
7c80: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66   less than 100 f
7c90: 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a  or its own use..
7ca0: 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ** A [SQLITE_FCN
7cb0: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c  TL_LOCKSTATE | l
7cc0: 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20  ist of opcodes] 
7cd0: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73  less than 100 is
7ce0: 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41   available..** A
7cf0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
7d00: 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d   define a custom
7d10: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
7d20: 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20  thod should use 
7d30: 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74  opcodes.** great
7d40: 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61  er than 100 to a
7d50: 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20  void conflicts. 
7d60: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
7d70: 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  ions should.** r
7d80: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f  eturn [SQLITE_NO
7d90: 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65  TFOUND] for file
7da0: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73   control opcodes
7db0: 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
7dc0: 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a  t.** recognize..
7dd0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f  **.** The xSecto
7de0: 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72  rSize() method r
7df0: 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f  eturns the secto
7e00: 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a  r size of the.**
7e10: 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64   device that und
7e20: 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e  erlies the file.
7e30: 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a    The sector siz
7e40: 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69  e is the.** mini
7e50: 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63  mum write that c
7e60: 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20  an be performed 
7e70: 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69  without disturbi
7e80: 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65  ng.** other byte
7e90: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  s in the file.  
7ea0: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61  The xDeviceChara
7eb0: 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20  cteristics().** 
7ec0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
7ed0: 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63   bit vector desc
7ee0: 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73  ribing behaviors
7ef0: 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72   of the.** under
7f00: 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a  lying device:.**
7f10: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
7f20: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
7f30: 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  TOMIC].** <li> [
7f40: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7f50: 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC512].** <li> 
7f60: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7f70: 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC1K].** <li> 
7f80: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7f90: 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC2K].** <li> 
7fa0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7fb0: 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC4K].** <li> 
7fc0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7fd0: 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC8K].** <li> 
7fe0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7ff0: 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC16K].** <li>
8000: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8010: 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC32K].** <li
8020: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8030: 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC64K].** <l
8040: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8050: 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a  _SAFE_APPEND].**
8060: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8070: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a  CAP_SEQUENTIAL].
8080: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
8090: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
80a0: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
80b0: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
80c0: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
80d0: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
80e0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
80f0: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
8100: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
8110: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
8120: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
8130: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
8140: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
8150: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
8160: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
8170: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
8180: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
8190: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
81a0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
81b0: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
81c0: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
81d0: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
81e0: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
81f0: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
8200: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
8210: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
8220: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
8230: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
8240: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
8250: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
8260: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
8270: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
8280: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
8290: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
82a0: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
82b0: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
82c0: 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78  te()..**.** If x
82d0: 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53  Read() returns S
82e0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
82f0: 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 61  T_READ it must a
8300: 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74  lso fill.** in t
8310: 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f  he unread portio
8320: 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ns of the buffer
8330: 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20   with zeros.  A 
8340: 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c  VFS that.** fail
8350: 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  s to zero-fill s
8360: 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 74  hort reads might
8370: 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20   seem to work.  
8380: 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c  However,.** fail
8390: 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ure to zero-fill
83a0: 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c   short reads wil
83b0: 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61  l eventually lea
83c0: 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65  d to.** database
83d0: 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a   corruption..*/.
83e0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
83f0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
8400: 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  s sqlite3_io_met
8410: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
8420: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
8430: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
8440: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65  ;.  int (*xClose
8450: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8460: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29  ;.  int (*xRead)
8470: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8480: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
8490: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
84a0: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
84b0: 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66  Write)(sqlite3_f
84c0: 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ile*, const void
84d0: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
84e0: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
84f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e  );.  int (*xTrun
8500: 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69  cate)(sqlite3_fi
8510: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
8520: 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20  64 size);.  int 
8530: 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33  (*xSync)(sqlite3
8540: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67  _file*, int flag
8550: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  s);.  int (*xFil
8560: 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66  eSize)(sqlite3_f
8570: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8580: 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69  t64 *pSize);.  i
8590: 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69  nt (*xLock)(sqli
85a0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
85b0: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b  .  int (*xUnlock
85c0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
85d0: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
85e0: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63  CheckReservedLoc
85f0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
8600: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
8610: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f  .  int (*xFileCo
8620: 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66  ntrol)(sqlite3_f
8630: 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f  ile*, int op, vo
8640: 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74  id *pArg);.  int
8650: 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28   (*xSectorSize)(
8660: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8670: 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43    int (*xDeviceC
8680: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28  haracteristics)(
8690: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
86a0: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f    /* Methods abo
86b0: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72  ve are valid for
86c0: 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20   version 1 */.  
86d0: 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73  int (*xShmMap)(s
86e0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
86f0: 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c  t iPg, int pgsz,
8700: 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74   int, void volat
8710: 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  ile**);.  int (*
8720: 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65  xShmLock)(sqlite
8730: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66  3_file*, int off
8740: 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20  set, int n, int 
8750: 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28  flags);.  void (
8760: 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73 71  *xShmBarrier)(sq
8770: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8780: 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29  int (*xShmUnmap)
8790: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
87a0: 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b  int deleteFlag);
87b0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
87c0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
87d0: 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20  r version 2 */. 
87e0: 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28 73   int (*xFetch)(s
87f0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8800: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8810: 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69  t, int iAmt, voi
8820: 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28  d **pp);.  int (
8830: 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74  *xUnfetch)(sqlit
8840: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
8850: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76  3_int64 iOfst, v
8860: 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65  oid *p);.  /* Me
8870: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
8880: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
8890: 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69  n 3 */.  /* Addi
88a0: 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d  tional methods m
88b0: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
88c0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a  uture releases *
88d0: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
88e0: 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46  3REF: Standard F
88f0: 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f  ile Control Opco
8900: 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  des.**.** These 
8910: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
8920: 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f  s are opcodes fo
8930: 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  r the xFileContr
8940: 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20  ol method.** of 
8950: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
8960: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
8970: 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c  and for the [sql
8980: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
8990: 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  l()].** interfac
89a0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  e..**.** The [SQ
89b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
89c0: 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  TATE] opcode is 
89d0: 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69  used for debuggi
89e0: 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63  ng.  This.** opc
89f0: 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78  ode causes the x
8a00: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
8a10: 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20  od to write the 
8a20: 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66  current state of
8a30: 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e  .** the lock (on
8a40: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  e of [SQLITE_LOC
8a50: 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  K_NONE], [SQLITE
8a60: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a  _LOCK_SHARED],.*
8a70: 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  * [SQLITE_LOCK_R
8a80: 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54  ESERVED], [SQLIT
8a90: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
8aa0: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b   or [SQLITE_LOCK
8ab0: 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20  _EXCLUSIVE]).** 
8ac0: 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  into an integer 
8ad0: 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72  that the pArg ar
8ae0: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f  gument points to
8af0: 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74  . This capabilit
8b00: 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72  y.** is used dur
8b10: 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20  ing testing and 
8b20: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65  only needs to be
8b30: 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20   supported when 
8b40: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69  SQLITE_TEST.** i
8b50: 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75  s defined..** <u
8b60: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  l>.** <li>[[SQLI
8b70: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
8b80: 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  NT]].** The [SQL
8b90: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
8ba0: 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  INT] opcode is u
8bb0: 73 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f  sed by SQLite to
8bc0: 20 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a   give the VFS.**
8bd0: 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66   layer a hint of
8be0: 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64   how large the d
8bf0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c  atabase file wil
8c00: 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72  l grow to be dur
8c10: 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65  ing the.** curre
8c20: 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20  nt transaction. 
8c30: 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f   This hint is no
8c40: 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20  t guaranteed to 
8c50: 62 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20  be accurate but 
8c60: 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63  it.** is often c
8c70: 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72  lose.  The under
8c80: 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20  lying VFS might 
8c90: 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c  choose to preall
8ca0: 6f 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a  ocate database.*
8cb0: 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73  * file space bas
8cc0: 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20  ed on this hint 
8cd0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70  in order to help
8ce0: 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64   writes to the d
8cf0: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
8d00: 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a  run faster..**.*
8d10: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
8d20: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d  CNTL_CHUNK_SIZE]
8d30: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
8d40: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
8d50: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
8d60: 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61  d to request tha
8d70: 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74  t the VFS.** ext
8d80: 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74  ends and truncat
8d90: 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
8da0: 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f  file in chunks o
8db0: 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69  f a size specifi
8dc0: 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65  ed.** by the use
8dd0: 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72  r. The fourth ar
8de0: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
8df0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
8e00: 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f  )] should .** po
8e10: 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  int to an intege
8e20: 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e  r (type int) con
8e30: 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20  taining the new 
8e40: 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73  chunk-size to us
8e50: 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d  e.** for the nom
8e60: 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e  inated database.
8e70: 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61   Allocating data
8e80: 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20  base file space 
8e90: 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e  in large.** chun
8ea0: 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61  ks (say 1MB at a
8eb0: 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75   time), may redu
8ec0: 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66  ce file-system f
8ed0: 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64  ragmentation and
8ee0: 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66  .** improve perf
8ef0: 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20  ormance on some 
8f00: 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c  systems..**.** <
8f10: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
8f20: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d  L_FILE_POINTER]]
8f30: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8f40: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
8f50: 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  ER] opcode is us
8f60: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70  ed to obtain a p
8f70: 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
8f80: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
8f90: 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65  object associate
8fa0: 64 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  d with a particu
8fb0: 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  lar database.** 
8fc0: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65  connection.  See
8fd0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
8fe0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f  le_control()] do
8ff0: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  cumentation for.
9000: 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** additional in
9010: 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
9020: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9030: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
9040: 5d 5d 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  ]].** ^(The [SQL
9050: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
9060: 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65 20 69  MITTED] opcode i
9070: 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65  s generated inte
9080: 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 51 4c  rnally by.** SQL
9090: 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74 6f 20  ite and sent to 
90a0: 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70 6c 61  all VFSes in pla
90b0: 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74 6f 20  ce of a call to 
90c0: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64  the xSync method
90d0: 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64 61 74  .** when the dat
90e0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
90f0: 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73 79 6e   has [PRAGMA syn
9100: 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20 74 6f  chronous] set to
9110: 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65 20   OFF.)^.** Some 
9120: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
9130: 73 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  s need this sign
9140: 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 6f  al in order to o
9150: 70 65 72 61 74 65 20 63 6f 72 72 65 63 74 6c 79  perate correctly
9160: 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47 4d 41  .** when [PRAGMA
9170: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50   synchronous | P
9180: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
9190: 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c 20 62  s=OFF] is set, b
91a0: 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 53 65  ut most .** VFSe
91b0: 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68  s do not need th
91c0: 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20 73 68  is signal and sh
91d0: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67  ould silently ig
91e0: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65  nore this opcode
91f0: 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
9200: 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c  s should not cal
9210: 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  l [sqlite3_file_
9220: 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20  control()] with 
9230: 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61  this.** opcode a
9240: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64  s doing so may d
9250: 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61  isrupt the opera
9260: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
9270: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a 2a  ialized VFSes.**
9280: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65   that do require
9290: 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69   it.  .**.** <li
92a0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
92b0: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d  WIN32_AV_RETRY]]
92c0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
92d0: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
92e0: 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73  RETRY] opcode is
92f0: 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75   used to configu
9300: 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20  re automatic.** 
9310: 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64  retry counts and
9320: 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63   intervals for c
9330: 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20  ertain disk I/O 
9340: 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74  operations for t
9350: 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56  he.** windows [V
9360: 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  FS] in order to 
9370: 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65  provide robustne
9380: 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e  ss in the presen
9390: 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69  ce of.** anti-vi
93a0: 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42  rus programs.  B
93b0: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77  y default, the w
93c0: 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20  indows VFS will 
93d0: 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c  retry file read,
93e0: 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20  .** file write, 
93f0: 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20  and file delete 
9400: 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f  operations up to
9410: 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20   10 times, with 
9420: 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35  a delay.** of 25
9430: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65   milliseconds be
9440: 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72  fore the first r
9450: 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68  etry and with th
9460: 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69  e delay increasi
9470: 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69  ng.** by an addi
9480: 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73  tional 25 millis
9490: 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68  econds with each
94a0: 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72   subsequent retr
94b0: 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  y.  This.** opco
94c0: 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20  de allows these 
94d0: 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72  two values (10 r
94e0: 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69  etries and 25 mi
94f0: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65  lliseconds of de
9500: 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64  lay).** to be ad
9510: 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c  justed.  The val
9520: 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20  ues are changed 
9530: 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65  for all database
9540: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
9550: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
9560: 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72  process.  The ar
9570: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
9580: 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20  ter to an array 
9590: 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65  of two.** intege
95a0: 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72  rs where the fir
95b0: 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 65  st integer i the
95c0: 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74   new retry count
95d0: 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a   and the second.
95e0: 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68  ** integer is th
95f0: 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74  e delay.  If eit
9600: 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e  her integer is n
9610: 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
9620: 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20  e setting.** is 
9630: 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20  not changed but 
9640: 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f  instead the prio
9650: 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  r value of that 
9660: 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74  setting is writt
9670: 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61  en.** into the a
9680: 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f  rray entry, allo
9690: 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74  wing the current
96a0: 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20   retry settings 
96b0: 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f  to be.** interro
96c0: 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e  gated.  The zDbN
96d0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
96e0: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
96f0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9700: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d  TL_PERSIST_WAL]]
9710: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
9720: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
9730: 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  AL] opcode is us
9740: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65  ed to set or que
9750: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73  ry the.** persis
9760: 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74  tent [WAL | Writ
9770: 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74  e Ahead Log] set
9780: 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c  ting.  By defaul
9790: 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79  t, the auxiliary
97a0: 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20  .** write ahead 
97b0: 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d  log and shared m
97c0: 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64  emory files used
97d0: 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e   for transaction
97e0: 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20   control.** are 
97f0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
9800: 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c  leted when the l
9810: 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e  atest connection
9820: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
9830: 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74  .** closes.  Set
9840: 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20  ting persistent 
9850: 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20  WAL mode causes 
9860: 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70  those files to p
9870: 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20  ersist after.** 
9880: 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69  close.  Persisti
9890: 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20  ng the files is 
98a0: 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65  useful when othe
98b0: 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74  r processes that
98c0: 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20   do not.** have 
98d0: 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e  write permission
98e0: 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72   on the director
98f0: 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  y containing the
9900: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
9910: 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74  ant.** to read t
9920: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9930: 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64  , as the WAL and
9940: 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66   shared memory f
9950: 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a  iles must exist.
9960: 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20  ** in order for 
9970: 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20  the database to 
9980: 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  be readable.  Th
9990: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
99a0: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
99b0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
99c0: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  ] for this opcod
99d0: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f  e should be a po
99e0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
99f0: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74  ger..** That int
9a00: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73  eger is 0 to dis
9a10: 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20  able persistent 
9a20: 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f  WAL mode or 1 to
9a30: 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65   enable persiste
9a40: 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20  nt.** WAL mode. 
9a50: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20   If the integer 
9a60: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69  is -1, then it i
9a70: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
9a80: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  th the current.*
9a90: 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63  * WAL persistenc
9aa0: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  e setting..**.**
9ab0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9ac0: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
9ad0: 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68  ERWRITE]].** ^Th
9ae0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9af0: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
9b00: 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  ITE] opcode is u
9b10: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
9b20: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
9b30: 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65  stent "powersafe
9b40: 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22  -overwrite" or "
9b50: 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20  PSOW" setting.  
9b60: 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67  The PSOW setting
9b70: 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74  .** determines t
9b80: 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  he [SQLITE_IOCAP
9b90: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
9ba0: 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65  RITE] bit of the
9bb0: 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61  .** xDeviceChara
9bc0: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f  cteristics metho
9bd0: 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70  ds. The fourth p
9be0: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
9bf0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9c00: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
9c10: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
9c20: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
9c30: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
9c40: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
9c50: 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d  to disable zero-
9c60: 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31  damage mode or 1
9c70: 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d   to enable zero-
9c80: 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20  damage.** mode. 
9c90: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20   If the integer 
9ca0: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69  is -1, then it i
9cb0: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
9cc0: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  th the current.*
9cd0: 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f  * zero-damage mo
9ce0: 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a  de setting..**.*
9cf0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9d00: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d  CNTL_OVERWRITE]]
9d10: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
9d20: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
9d30: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f  ] opcode is invo
9d40: 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66  ked by SQLite af
9d50: 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61  ter opening.** a
9d60: 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69   write transacti
9d70: 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  on to indicate t
9d80: 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69  hat, unless it i
9d90: 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f  s rolled back fo
9da0: 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e  r some.** reason
9db0: 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74  , the entire dat
9dc0: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20  abase file will 
9dd0: 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62  be overwritten b
9de0: 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a  y the current .*
9df0: 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54  * transaction. T
9e00: 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56  his is used by V
9e10: 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73  ACUUM operations
9e20: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9e30: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
9e40: 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ME]].** ^The [SQ
9e50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
9e60: 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62  ME] opcode can b
9e70: 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
9e80: 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a   the names of.**
9e90: 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20   all [VFSes] in 
9ea0: 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20  the VFS stack.  
9eb0: 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66  The names are of
9ec0: 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61   all VFS shims a
9ed0: 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  nd the.** final 
9ee0: 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53  bottom-level VFS
9ef0: 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74   are written int
9f00: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
9f10: 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69  d from .** [sqli
9f20: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
9f30: 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  d the result is 
9f40: 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68  stored in the ch
9f50: 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  ar* variable.** 
9f60: 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20  that the fourth 
9f70: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71  parameter of [sq
9f80: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9f90: 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e  ol()] points to.
9fa0: 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69  .** The caller i
9fb0: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
9fc0: 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65  r freeing the me
9fd0: 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20  mory when done. 
9fe0: 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20   As with.** all 
9ff0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74  file-control act
a000: 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e  ions, there is n
a010: 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  o guarantee that
a020: 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61   this will actua
a030: 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69  lly.** do anythi
a040: 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f  ng.  Callers sho
a050: 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74  uld initialize t
a060: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
a070: 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  e to a NULL.** p
a080: 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74  ointer in case t
a090: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
a0a0: 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e   is not implemen
a0b0: 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d  ted.  This file-
a0c0: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e  control.** is in
a0d0: 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e  tended for diagn
a0e0: 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a  ostic use only..
a0f0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a100: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a110: 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61  ].** ^Whenever a
a120: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d   [PRAGMA] statem
a130: 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61  ent is parsed, a
a140: 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  n [SQLITE_FCNTL_
a150: 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65  PRAGMA] .** file
a160: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74   control is sent
a170: 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71   to the open [sq
a180: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
a190: 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  ct corresponding
a1a0: 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62  .** to the datab
a1b0: 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63  ase file to whic
a1c0: 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61  h the pragma sta
a1d0: 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e  tement refers. ^
a1e0: 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  The argument.** 
a1f0: 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  to the [SQLITE_F
a200: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
a210: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20  e control is an 
a220: 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e  array of.** poin
a230: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
a240: 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63  (char**) in whic
a250: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65  h the second ele
a260: 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61  ment of the arra
a270: 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  y.** is the name
a280: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61   of the pragma a
a290: 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65  nd the third ele
a2a0: 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75  ment is the argu
a2b0: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70  ment to the.** p
a2c0: 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66  ragma or NULL if
a2d0: 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20   the pragma has 
a2e0: 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54  no argument.  ^T
a2f0: 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  he handler for a
a300: 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  n.** [SQLITE_FCN
a310: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
a320: 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69  control can opti
a330: 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20  onally make the 
a340: 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a  first element.**
a350: 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61   of the char** a
a360: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f  rgument point to
a370: 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e   a string obtain
a380: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
a390: 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f  _mprintf()].** o
a3a0: 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74  r the equivalent
a3b0: 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67   and that string
a3c0: 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65   will become the
a3d0: 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70   result of the p
a3e0: 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20  ragma or.** the 
a3f0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66  error message if
a400: 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c   the pragma fail
a410: 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  s. ^If the.** [S
a420: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
a430: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
a440: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
a450: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e  _NOTFOUND], then
a460: 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41   normal .** [PRA
a470: 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20  GMA] processing 
a480: 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20  continues.  ^If 
a490: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
a4a0: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c  L_PRAGMA].** fil
a4b0: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
a4c0: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
a4d0: 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61  hen the parser a
a4e0: 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
a4f0: 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c  ** VFS has handl
a500: 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74  ed the PRAGMA it
a510: 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72  self and the par
a520: 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20  ser generates a 
a530: 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65  no-op.** prepare
a540: 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49  d statement.  ^I
a550: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  f the [SQLITE_FC
a560: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
a570: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
a580: 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63  .** any result c
a590: 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ode other than [
a5a0: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53  SQLITE_OK] or [S
a5b0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
a5c0: 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74   that means.** t
a5d0: 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f  hat the VFS enco
a5e0: 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72  untered an error
a5f0: 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20   while handling 
a600: 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64  the [PRAGMA] and
a610: 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74   the.** compilat
a620: 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d  ion of the PRAGM
a630: 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20  A fails with an 
a640: 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51  error.  ^The [SQ
a650: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
a660: 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72  A].** file contr
a670: 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 65  ol occurs at the
a680: 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72   beginning of pr
a690: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61  agma statement a
a6a0: 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a  nalysis and so.*
a6b0: 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20  * it is able to 
a6c0: 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69  override built-i
a6d0: 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65  n [PRAGMA] state
a6e0: 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ments..**.** <li
a6f0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a700: 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a  BUSYHANDLER]].**
a710: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
a720: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d  NTL_BUSYHANDLER]
a730: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  .** file-control
a740: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
a750: 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65  by SQLite on the
a760: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 68   database file h
a770: 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79  andle.** shortly
a780: 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70 65   after it is ope
a790: 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ned in order to 
a7a0: 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d  provide a custom
a7b0: 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73 73   VFS with access
a7c0: 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65  .** to the conne
a7d0: 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64  ctions busy-hand
a7e0: 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68  ler callback. Th
a7f0: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66  e argument is of
a800: 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a   type (void **).
a810: 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66  ** - an array of
a820: 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61   two (void *) va
a830: 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74 20  lues. The first 
a840: 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c  (void *) actuall
a850: 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61  y points.** to a
a860: 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70   function of typ
a870: 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20  e (int (*)(void 
a880: 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f  *)). In order to
a890: 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e   invoke the conn
a8a0: 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d  ections.** busy-
a8b0: 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75  handler, this fu
a8c0: 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65  nction should be
a8d0: 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68   invoked with th
a8e0: 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a  e second (void *
a8f0: 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61  ) in.** the arra
a900: 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72  y as the only ar
a910: 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65  gument. If it re
a920: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
a930: 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69  then the operati
a940: 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
a950: 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20 72  retried. If it r
a960: 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65  eturns zero, the
a970: 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75   custom VFS shou
a980: 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a  ld abandon the.*
a990: 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74  * current operat
a9a0: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ion..**.** <li>[
a9b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45  [SQLITE_FCNTL_TE
a9c0: 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20  MPFILENAME]].** 
a9d0: 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e  ^Application can
a9e0: 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c   invoke the [SQL
a9f0: 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49  ITE_FCNTL_TEMPFI
aa00: 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e  LENAME] file-con
aa10: 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20  trol.** to have 
aa20: 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20  SQLite generate 
aa30: 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  a.** temporary f
aa40: 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68  ilename using th
aa50: 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d  e same algorithm
aa60: 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65   that is followe
aa70: 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a  d to generate.**
aa80: 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e   temporary filen
aa90: 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61  ames for TEMP ta
aaa0: 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69  bles and other i
aab0: 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54  nternal uses.  T
aac0: 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73  he.** argument s
aad0: 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a  hould be a char*
aae0: 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20  * which will be 
aaf0: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
ab00: 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74  filename.** writ
ab10: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  ten into memory 
ab20: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
ab30: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
ab40: 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68  .  The caller sh
ab50: 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b  ould.** invoke [
ab60: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
ab70: 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f  on the result to
ab80: 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20   avoid a memory 
ab90: 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  leak..**.** <li>
aba0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d  [[SQLITE_FCNTL_M
abb0: 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68  MAP_SIZE]].** Th
abc0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
abd0: 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20  MMAP_SIZE] file 
abe0: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
abf0: 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74 20  to query or set 
ac00: 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e  the.** maximum n
ac10: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 74  umber of bytes t
ac20: 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64  hat will be used
ac30: 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70   for memory-mapp
ac40: 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61  ed I/O..** The a
ac50: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
ac60: 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20  nter to a value 
ac70: 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f  of type sqlite3_
ac80: 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73  int64 that.** is
ac90: 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78   an advisory max
aca0: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62  imum number of b
acb0: 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65  ytes in the file
acc0: 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20   to memory map. 
acd0: 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   The.** pointer 
ace0: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
acf0: 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75  ith the old valu
ad00: 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73  e.  The limit is
ad10: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a   not changed if.
ad20: 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69  ** the value ori
ad30: 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20  ginally pointed 
ad40: 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  to is negative, 
ad50: 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72 65  and so the curre
ad60: 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e  nt limit .** can
ad70: 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20 70   be queried by p
ad80: 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e  assing in a poin
ad90: 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76  ter to a negativ
ada0: 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a  e number.  This.
adb0: 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  ** file-control 
adc0: 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
add0: 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ly to implement 
ade0: 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  [PRAGMA mmap_siz
adf0: 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a  e]..**.** </ul>.
ae00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
ae10: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
ae20: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
ae30: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
ae40: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
ae50: 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20 32  LE             2
ae60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ae70: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
ae80: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a  E             3.
ae90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
aea0: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20  AST_ERRNO       
aeb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23               4.#
aec0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
aed0: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20  NTL_SIZE_HINT   
aee0: 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
aef0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
af00: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20  TL_CHUNK_SIZE   
af10: 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
af20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
af30: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20  L_FILE_POINTER  
af40: 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
af50: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
af60: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20  _SYNC_OMITTED   
af70: 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69           8.#defi
af80: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
af90: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20  WIN32_AV_RETRY  
afa0: 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e          9.#defin
afb0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
afc0: 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20  ERSIST_WAL      
afd0: 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65        10.#define
afe0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56   SQLITE_FCNTL_OV
aff0: 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20  ERWRITE         
b000: 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20       11.#define 
b010: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
b020: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20  NAME            
b030: 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53      12.#define S
b040: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
b050: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
b060: 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51     13.#define SQ
b070: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
b080: 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
b090: 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c    14.#define SQL
b0a0: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
b0b0: 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 20  NDLER           
b0c0: 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   15.#define SQLI
b0d0: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c  TE_FCNTL_TEMPFIL
b0e0: 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20  ENAME           
b0f0: 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  16.#define SQLIT
b100: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
b110: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31  E              1
b120: 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  8../*.** CAPI3RE
b130: 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a  F: Mutex Handle.
b140: 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20  **.** The mutex 
b150: 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51  module within SQ
b160: 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71  Lite defines [sq
b170: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20  lite3_mutex] to 
b180: 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63  be an.** abstrac
b190: 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74  t type for a mut
b1a0: 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  ex object.  The 
b1b0: 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65  SQLite core neve
b1c0: 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68  r looks.** at th
b1d0: 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
b1e0: 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  sentation of an 
b1f0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e  [sqlite3_mutex].
b200: 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61    It only.** dea
b210: 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73  ls with pointers
b220: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
b230: 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a  _mutex] object..
b240: 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72  **.** Mutexes ar
b250: 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  e created using 
b260: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
b270: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  lloc()]..*/.type
b280: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
b290: 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33  e3_mutex sqlite3
b2a0: 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _mutex;../*.** C
b2b0: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
b2c0: 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a  rface Object.**.
b2d0: 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
b2e0: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
b2f0: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
b300: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
b310: 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51  etween.** the SQ
b320: 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68  Lite core and th
b330: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65  e underlying ope
b340: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
b350: 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20  The "vfs".** in 
b360: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
b370: 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f  object stands fo
b380: 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20  r "virtual file 
b390: 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a  system".  See.**
b3a0: 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20   the [VFS | VFS 
b3b0: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
b3c0: 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72  or further infor
b3d0: 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
b3e0: 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69  e value of the i
b3f0: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73  Version field is
b400: 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74   initially 1 but
b410: 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69   may be larger i
b420: 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73  n.** future vers
b430: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ions of SQLite. 
b440: 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   Additional fiel
b450: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
b460: 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62  ed to this.** ob
b470: 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56  ject when the iV
b480: 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20  ersion value is 
b490: 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65  increased.  Note
b4a0: 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74   that the struct
b4b0: 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  ure.** of the sq
b4c0: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
b4d0: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
b4e0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77  transaction betw
b4f0: 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  een.** SQLite ve
b500: 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20  rsion 3.5.9 and 
b510: 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68  3.6.0 and yet th
b520: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64  e iVersion field
b530: 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69   was not.** modi
b540: 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fied..**.** The 
b550: 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69  szOsFile field i
b560: 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
b570: 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71  e subclassed [sq
b580: 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73  lite3_file].** s
b590: 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79  tructure used by
b5a0: 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61   this VFS.  mxPa
b5b0: 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61  thname is the ma
b5c0: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a  ximum length of.
b5d0: 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e  ** a pathname in
b5e0: 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a   this VFS..**.**
b5f0: 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69   Registered sqli
b600: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20  te3_vfs objects 
b610: 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69  are kept on a li
b620: 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64  nked list formed
b630: 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74   by.** the pNext
b640: 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b   pointer.  The [
b650: 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69  sqlite3_vfs_regi
b660: 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  ster()].** and [
b670: 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
b680: 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66  gister()] interf
b690: 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73  aces manage this
b6a0: 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68   list.** in a th
b6b0: 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20  read-safe way.  
b6c0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
b6d0: 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61  _find()] interfa
b6e0: 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74  ce.** searches t
b6f0: 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65  he list.  Neithe
b700: 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
b710: 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56  n code nor the V
b720: 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  FS.** implementa
b730: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20  tion should use 
b740: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
b750: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65  r..**.** The pNe
b760: 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  xt field is the 
b770: 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68  only field in th
b780: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
b790: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
b7a0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72  SQLite will ever
b7b0: 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65   modify.  SQLite
b7c0: 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73   will only acces
b7d0: 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74  s.** or modify t
b7e0: 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20  his field while 
b7f0: 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63  holding a partic
b800: 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65  ular static mute
b810: 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  x..** The applic
b820: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76  ation should nev
b830: 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69  er modify anythi
b840: 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71  ng within the sq
b850: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a  lite3_vfs.** obj
b860: 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a  ect once the obj
b870: 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67  ect has been reg
b880: 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  istered..**.** T
b890: 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68  he zName field h
b8a0: 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  olds the name of
b8b0: 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e   the VFS module.
b8c0: 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a    The name must.
b8d0: 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72  ** be unique acr
b8e0: 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75  oss all VFS modu
b8f0: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  les..**.** [[sql
b900: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d  ite3_vfs.xOpen]]
b910: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72  .** ^SQLite guar
b920: 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
b930: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
b940: 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20  ter to xOpen.** 
b950: 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  is either a NULL
b960: 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69   pointer or stri
b970: 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ng obtained.** f
b980: 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  rom xFullPathnam
b990: 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69  e() with an opti
b9a0: 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65  onal suffix adde
b9b0: 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66  d..** ^If a suff
b9c0: 69 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74  ix is added to t
b9d0: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
b9e0: 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a  ameter, it will.
b9f0: 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20  ** consist of a 
ba00: 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61  single "-" chara
ba10: 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79  cter followed by
ba20: 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a   no more than.**
ba30: 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   11 alphanumeric
ba40: 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72   and/or "-" char
ba50: 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69  acters..** ^SQLi
ba60: 74 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61  te further guara
ba70: 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  ntees that.** th
ba80: 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  e string will be
ba90: 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61   valid and uncha
baa0: 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73  nged until xClos
bab0: 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64  e() is.** called
bac0: 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65  . Because of the
bad0: 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
bae0: 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ce,.** the [sqli
baf0: 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61  te3_file] can sa
bb00: 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69  fely store a poi
bb10: 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66  nter to the.** f
bb20: 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65  ilename if it ne
bb30: 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  eds to remember 
bb40: 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72  the filename for
bb50: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a   some reason..**
bb60: 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   If the zFilenam
bb70: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
bb80: 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70  Open is a NULL p
bb90: 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65  ointer then xOpe
bba0: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74  n.** must invent
bbb0: 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61   its own tempora
bbc0: 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20  ry name for the 
bbd0: 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72  file.  ^Whenever
bbe0: 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61   the .** xFilena
bbf0: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  me parameter is 
bc00: 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73  NULL it will als
bc10: 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  o be the case th
bc20: 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20  at the.** flags 
bc30: 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69  parameter will i
bc40: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
bc50: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
bc60: 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  E]..**.** The fl
bc70: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
bc80: 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73  xOpen() includes
bc90: 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e   all bits set in
bca0: 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72  .** the flags ar
bcb0: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
bcc0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20  e3_open_v2()].  
bcd0: 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f  Or if [sqlite3_o
bce0: 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  pen()].** or [sq
bcf0: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
bd00: 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c  is used, then fl
bd10: 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20  ags includes at 
bd20: 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45  least.** [SQLITE
bd30: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
bd40: 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
bd50: 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20  CREATE]. .** If 
bd60: 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20  xOpen() opens a 
bd70: 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74  file read-only t
bd80: 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75  hen it sets *pOu
bd90: 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63  tFlags to.** inc
bda0: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
bdb0: 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74  N_READONLY].  Ot
bdc0: 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75  her bits in *pOu
bdd0: 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65  tFlags may be se
bde0: 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74  t..**.** ^(SQLit
bdf0: 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20  e will also add 
be00: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
be10: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
be20: 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c  e xOpen().** cal
be30: 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  l, depending on 
be40: 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67  the object being
be50: 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c   opened:.**.** <
be60: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  ul>.** <li>  [SQ
be70: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
be80: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
be90: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
bea0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
beb0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
bec0: 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  P_DB].** <li>  [
bed0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
bee0: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
bef0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
bf00: 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a  TRANSIENT_DB].**
bf10: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
bf20: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a  PEN_SUBJOURNAL].
bf30: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
bf40: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
bf50: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
bf60: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d  SQLITE_OPEN_WAL]
bf70: 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
bf80: 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69  * The file I/O i
bf90: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61  mplementation ca
bfa0: 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74  n use the object
bfb0: 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a   type flags to.*
bfc0: 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79  * change the way
bfd0: 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66   it deals with f
bfe0: 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70  iles.  For examp
bff0: 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
c000: 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20  on.** that does 
c010: 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63  not care about c
c020: 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72  rash recovery or
c030: 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   rollback might 
c040: 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e  make.** the open
c050: 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69   of a journal fi
c060: 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69  le a no-op.  Wri
c070: 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72  tes to this jour
c080: 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73  nal would.** als
c090: 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64  o be no-ops, and
c0a0: 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   any attempt to 
c0b0: 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c  read the journal
c0c0: 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a   would return.**
c0d0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20   SQLITE_IOERR.  
c0e0: 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  Or the implement
c0f0: 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f  ation might reco
c100: 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74  gnize that a dat
c110: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69  abase.** file wi
c120: 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65  ll be doing page
c130: 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20  -aligned sector 
c140: 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73  reads and writes
c150: 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20   in a random.** 
c160: 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70  order and set up
c170: 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74   its I/O subsyst
c180: 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a  em accordingly..
c190: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67  **.** SQLite mig
c1a0: 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ht also add one 
c1b0: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
c1c0: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
c1d0: 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  pen method:.**.*
c1e0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
c1f0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
c200: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c  TEONCLOSE].** <l
c210: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
c220: 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f  EXCLUSIVE].** </
c230: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ul>.**.** The [S
c240: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
c250: 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d  EONCLOSE] flag m
c260: 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68  eans the file sh
c270: 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74  ould be.** delet
c280: 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c  ed when it is cl
c290: 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c  osed.  ^The [SQL
c2a0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
c2b0: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20  NCLOSE].** will 
c2c0: 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20  be set for TEMP 
c2d0: 64 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68  databases and th
c2e0: 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72  eir journals, tr
c2f0: 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62  ansient.** datab
c300: 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75  ases, and subjou
c310: 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rnals..**.** ^Th
c320: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  e [SQLITE_OPEN_E
c330: 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69  XCLUSIVE] flag i
c340: 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e  s always used in
c350: 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20   conjunction.** 
c360: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
c370: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c  _OPEN_CREATE] fl
c380: 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f  ag, which are bo
c390: 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61  th directly.** a
c3a0: 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20  nalogous to the 
c3b0: 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45  O_EXCL and O_CRE
c3c0: 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20  AT flags of the 
c3d0: 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20  POSIX open().** 
c3e0: 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45  API.  The SQLITE
c3f0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
c400: 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65  flag, when paire
c410: 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53  d with the .** S
c420: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
c430: 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e  E, is used to in
c440: 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65  dicate that file
c450: 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a   should always.*
c460: 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e  * be created, an
c470: 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20  d that it is an 
c480: 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65  error if it alre
c490: 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49  ady exists..** I
c4a0: 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20  t is <i>not</i> 
c4b0: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
c4c0: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
c4d0: 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66   be opened .** f
c4e0: 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63  or exclusive acc
c4f0: 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c  ess..**.** ^At l
c500: 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79  east szOsFile by
c510: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72  tes of memory ar
c520: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53  e allocated by S
c530: 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64  QLite.** to hold
c540: 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66   the  [sqlite3_f
c550: 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70  ile] structure p
c560: 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69  assed as the thi
c570: 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  rd.** argument t
c580: 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f  o xOpen.  The xO
c590: 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20  pen method does 
c5a0: 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61  not have to.** a
c5b0: 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75  llocate the stru
c5c0: 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64  cture; it should
c5d0: 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e   just fill it in
c5e0: 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20  .  Note that.** 
c5f0: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
c600: 20 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71   must set the sq
c610: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
c620: 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a  ods to either.**
c630: 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65   a valid [sqlite
c640: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
c650: 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e  ject or to NULL.
c660: 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a    xOpen must do.
c670: 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20  ** this even if 
c680: 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20  the open fails. 
c690: 20 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20   SQLite expects 
c6a0: 74 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33  that the sqlite3
c6b0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a  _file.pMethods.*
c6c0: 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62  * element will b
c6d0: 65 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f  e valid after xO
c6e0: 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61  pen returns rega
c6f0: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75  rdless of the su
c700: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c  ccess.** or fail
c710: 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e  ure of the xOpen
c720: 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73   call..**.** [[s
c730: 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65  qlite3_vfs.xAcce
c740: 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61  ss]].** ^The fla
c750: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
c760: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
c770: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
c780: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73  XISTS].** to tes
c790: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65  t for the existe
c7a0: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f  nce of a file, o
c7b0: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
c7c0: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a  _READWRITE] to.*
c7d0: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  * test whether a
c7e0: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
c7f0: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
c800: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
c810: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
c820: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
c830: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65  e is at least re
c840: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69  adable.   The fi
c850: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
c860: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
c870: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77  ^SQLite will alw
c880: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20  ays allocate at 
c890: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65  least mxPathname
c8a0: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65  +1 bytes for the
c8b0: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65  .** output buffe
c8c0: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e  r xFullPathname.
c8d0: 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65    The exact size
c8e0: 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   of the output b
c8f0: 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f  uffer.** is also
c900: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72   passed as a par
c910: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20  ameter to both  
c920: 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20  methods. If the 
c930: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
c940: 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e   is not large en
c950: 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41  ough, [SQLITE_CA
c960: 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62  NTOPEN] should b
c970: 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63  e returned. Sinc
c980: 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e  e this is.** han
c990: 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20  dled as a fatal 
c9a0: 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c  error by SQLite,
c9b0: 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   vfs implementat
c9c0: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65  ions should ende
c9d0: 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65  avor.** to preve
c9e0: 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69  nt this by setti
c9f0: 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f  ng mxPathname to
ca00: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20   a sufficiently 
ca10: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a  large value..**.
ca20: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
ca30: 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20  ss(), xSleep(), 
ca40: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20  xCurrentTime(), 
ca50: 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65  and xCurrentTime
ca60: 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72  Int64().** inter
ca70: 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74  faces are not st
ca80: 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66  rictly a part of
ca90: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c   the filesystem,
caa0: 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a   but they are.**
cab0: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
cac0: 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66   VFS structure f
cad0: 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e  or completeness.
cae0: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
caf0: 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61  ess() function a
cb00: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72  ttempts to retur
cb10: 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a  n nBytes bytes.*
cb20: 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74  * of good-qualit
cb30: 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  y randomness int
cb40: 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74  o zOut.  The ret
cb50: 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  urn value is.** 
cb60: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65  the actual numbe
cb70: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61  r of bytes of ra
cb80: 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
cb90: 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70  d..** The xSleep
cba0: 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73  () method causes
cbb0: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72   the calling thr
cbc0: 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72  ead to sleep for
cbd0: 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65   at.** least the
cbe0: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f   number of micro
cbf0: 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20  seconds given.  
cc00: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
cc10: 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  e().** method re
cc20: 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44  turns a Julian D
cc30: 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68  ay Number for th
cc40: 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61  e current date a
cc50: 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20  nd time as.** a 
cc60: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
cc70: 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43  alue..** ^The xC
cc80: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
cc90: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
cca0: 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c  , as an integer,
ccb0: 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44   the Julian.** D
ccc0: 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70  ay Number multip
ccd0: 6c 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30  lied by 86400000
cce0: 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   (the number of 
ccf0: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20  milliseconds in 
cd00: 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61  .** a 24-hour da
cd10: 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65  y).  .** ^SQLite
cd20: 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43   will use the xC
cd30: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
cd40: 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20  ) method to get 
cd50: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64  the current.** d
cd60: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20  ate and time if 
cd70: 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61  that method is a
cd80: 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65  vailable (if iVe
cd90: 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a  rsion is 2 or .*
cda0: 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68  * greater and th
cdb0: 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  e function point
cdc0: 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20  er is not NULL) 
cdd0: 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61  and will fall ba
cde0: 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e  ck.** to xCurren
cdf0: 74 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72  tTime() if xCurr
ce00: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69  entTimeInt64() i
ce10: 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a  s unavailable..*
ce20: 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79  *.** ^The xSetSy
ce30: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74  stemCall(), xGet
ce40: 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e  SystemCall(), an
ce50: 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c  d xNestSystemCal
ce60: 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  l() interfaces.*
ce70: 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62  * are not used b
ce80: 79 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  y the SQLite cor
ce90: 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e  e.  These option
cea0: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
ceb0: 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79  e provided.** by
cec0: 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66   some VFSes to f
ced0: 61 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e  acilitate testin
cee0: 67 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64  g of the VFS cod
cef0: 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67  e. By overriding
cf00: 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c   .** system call
cf10: 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73  s with functions
cf20: 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72   under its contr
cf30: 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72  ol, a test progr
cf40: 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61  am can.** simula
cf50: 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72  te faults and er
cf60: 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74  ror conditions t
cf70: 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77  hat would otherw
cf80: 69 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74  ise be difficult
cf90: 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c  .** or impossibl
cfa0: 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68  e to induce.  Th
cfb0: 65 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20  e set of system 
cfc0: 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62  calls that can b
cfd0: 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20  e overridden.** 
cfe0: 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20  varies from one 
cff0: 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20  VFS to another, 
d000: 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72  and from one ver
d010: 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65  sion of the same
d020: 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e   VFS to the.** n
d030: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
d040: 6e 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73  ns that use thes
d050: 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73  e interfaces mus
d060: 74 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f  t be prepared fo
d070: 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20  r any.** or all 
d080: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  of these interfa
d090: 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f  ces to be NULL o
d0a0: 72 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61  r for their beha
d0b0: 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a  vior to change.*
d0c0: 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61  * from one relea
d0d0: 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20  se to the next. 
d0e0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75   Applications mu
d0f0: 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74  st not attempt t
d100: 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20  o access.** any 
d110: 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73  of these methods
d120: 20 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e   if the iVersion
d130: 20 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c   of the VFS is l
d140: 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74  ess than 3..*/.t
d150: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
d160: 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65  lite3_vfs sqlite
d170: 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76  3_vfs;.typedef v
d180: 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79  oid (*sqlite3_sy
d190: 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29  scall_ptr)(void)
d1a0: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
d1b0: 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  _vfs {.  int iVe
d1c0: 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20  rsion;          
d1d0: 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76    /* Structure v
d1e0: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63  ersion number (c
d1f0: 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20  urrently 3) */. 
d200: 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20   int szOsFile;  
d210: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a            /* Siz
d220: 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20  e of subclassed 
d230: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a  sqlite3_file */.
d240: 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65    int mxPathname
d250: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61  ;          /* Ma
d260: 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e  ximum file pathn
d270: 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20  ame length */.  
d280: 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65  sqlite3_vfs *pNe
d290: 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74  xt;      /* Next
d2a0: 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20   registered VFS 
d2b0: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
d2c0: 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a  *zName;       /*
d2d0: 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69   Name of this vi
d2e0: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
d2f0: 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  m */.  void *pAp
d300: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
d310: 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70  /* Pointer to ap
d320: 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66  plication-specif
d330: 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74  ic data */.  int
d340: 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
d350: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
d360: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
d370: 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20  e3_file*,.      
d380: 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61           int fla
d390: 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61  gs, int *pOutFla
d3a0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  gs);.  int (*xDe
d3b0: 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lete)(sqlite3_vf
d3c0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
d3d0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44  zName, int syncD
d3e0: 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63  ir);.  int (*xAc
d3f0: 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  cess)(sqlite3_vf
d400: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
d410: 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73  zName, int flags
d420: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
d430: 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61  .  int (*xFullPa
d440: 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  thname)(sqlite3_
d450: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
d460: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75   *zName, int nOu
d470: 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  t, char *zOut);.
d480: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65    void *(*xDlOpe
d490: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
d4a0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
d4b0: 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20  lename);.  void 
d4c0: 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69  (*xDlError)(sqli
d4d0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
d4e0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d  yte, char *zErrM
d4f0: 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a  sg);.  void (*(*
d500: 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f  xDlSym)(sqlite3_
d510: 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73  vfs*,void*, cons
d520: 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29  t char *zSymbol)
d530: 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20  )(void);.  void 
d540: 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69  (*xDlClose)(sqli
d550: 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29  te3_vfs*, void*)
d560: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f  ;.  int (*xRando
d570: 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  mness)(sqlite3_v
d580: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
d590: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69  char *zOut);.  i
d5a0: 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c  nt (*xSleep)(sql
d5b0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d  ite3_vfs*, int m
d5c0: 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20  icroseconds);.  
d5d0: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
d5e0: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
d5f0: 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e  , double*);.  in
d600: 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f  t (*xGetLastErro
d610: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
d620: 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20   int, char *);. 
d630: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
d640: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
d650: 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74  n version 1 of t
d660: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
d670: 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69  ject.  ** defini
d680: 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61  tion.  Those tha
d690: 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64  t follow are add
d6a0: 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20  ed in version 2 
d6b0: 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20  or later.  */.  
d6c0: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
d6d0: 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33  meInt64)(sqlite3
d6e0: 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69  _vfs*, sqlite3_i
d6f0: 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a  nt64*);.  /*.  *
d700: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
d710: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
d720: 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74  ons 1 and 2 of t
d730: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
d740: 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65  ject..  ** Those
d750: 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76   below are for v
d760: 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65  ersion 3 and gre
d770: 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74  ater..  */.  int
d780: 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c   (*xSetSystemCal
d790: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
d7a0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
d7b0: 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63  me, sqlite3_sysc
d7c0: 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69  all_ptr);.  sqli
d7d0: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20  te3_syscall_ptr 
d7e0: 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xGetSystemCall
d7f0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
d800: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
d810: 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  e);.  const char
d820: 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43   *(*xNextSystemC
d830: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
d840: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
d850: 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  Name);.  /*.  **
d860: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
d870: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
d880: 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f  ns 1 through 3 o
d890: 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73  f the sqlite_vfs
d8a0: 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65   object..  ** Ne
d8b0: 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  w fields may be 
d8c0: 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75  appended in figu
d8d0: 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68  re versions.  Th
d8e0: 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20  e iVersion.  ** 
d8f0: 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65  value will incre
d900: 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68  ment whenever th
d910: 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a  is happens. .  *
d920: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
d930: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20  3REF: Flags for 
d940: 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20  the xAccess VFS 
d950: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
d960: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
d970: 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64  ants can be used
d980: 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61   as the third pa
d990: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
d9a0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
d9b0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
d9c0: 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  vfs] object.  Th
d9d0: 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20  ey determine.** 
d9e0: 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72  what kind of per
d9f0: 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63  missions the xAc
da00: 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c  cess method is l
da10: 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57  ooking for..** W
da20: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
da30: 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41  S_EXISTS, the xA
da40: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
da50: 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68  simply checks wh
da60: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65  ether the file e
da70: 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53  xists..** With S
da80: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
da90: 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63  DWRITE, the xAcc
daa0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
dab0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
dac0: 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79   named directory
dad0: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c   is both readabl
dae0: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a  e and writable.*
daf0: 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  * (in other word
db00: 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20  s, if files can 
db10: 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65  be added, remove
db20: 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77  d, and renamed w
db30: 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72  ithin.** the dir
db40: 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20  ectory)..** The 
db50: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
db60: 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74  ADWRITE constant
db70: 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73   is currently us
db80: 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a  ed only by the.*
db90: 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  * [temp_store_di
dba0: 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c  rectory pragma],
dbb0: 20 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75   though this cou
dbc0: 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66  ld change in a f
dbd0: 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65  uture.** release
dbe0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57   of SQLite..** W
dbf0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
dc00: 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63  S_READ, the xAcc
dc10: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
dc20: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
dc30: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
dc40: 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41  e.  The SQLITE_A
dc50: 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74  CCESS_READ const
dc60: 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e  ant is.** curren
dc70: 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75  tly unused, thou
dc80: 67 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75  gh it might be u
dc90: 73 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20  sed in a future 
dca0: 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51  release of.** SQ
dcb0: 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
dcc0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
dcd0: 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69  XISTS    0.#defi
dce0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
dcf0: 5f 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f  _READWRITE 1   /
dd00: 2a 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41  * Used by PRAGMA
dd10: 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65   temp_store_dire
dd20: 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ctory */.#define
dd30: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
dd40: 45 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20  EAD      2   /* 
dd50: 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  Unused */../*.**
dd60: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
dd70: 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63   for the xShmLoc
dd80: 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  k VFS method.**.
dd90: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
dda0: 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
ddb0: 65 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f  e the various lo
ddc0: 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73  cking operations
ddd0: 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74  .** allowed by t
dde0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
ddf0: 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69  od of [sqlite3_i
de00: 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65  o_methods].  The
de10: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72  .** following ar
de20: 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c  e the only legal
de30: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66   combinations of
de40: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a   flags to the.**
de50: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
de60: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
de70: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
de80: 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  _LOCK | SQLITE_S
de90: 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69  HM_SHARED.** <li
dea0: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  >  SQLITE_SHM_LO
deb0: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
dec0: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69  EXCLUSIVE.** <li
ded0: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  >  SQLITE_SHM_UN
dee0: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
def0: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
df00: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
df10: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
df20: 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f  _EXCLUSIVE.** </
df30: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75  ul>.**.** When u
df40: 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61  nlocking, the sa
df50: 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43  me SHARED or EXC
df60: 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74  LUSIVE flag must
df70: 20 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a   be supplied as.
df80: 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20  ** was given no 
df90: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
dfa0: 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20  g lock.  .**.** 
dfb0: 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  The xShmLock met
dfc0: 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69  hod can transiti
dfd0: 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  on between unloc
dfe0: 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f  ked and SHARED o
dff0: 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c  r.** between unl
e000: 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53  ocked and EXCLUS
e010: 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20  IVE.  It cannot 
e020: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
e030: 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64  en SHARED.** and
e040: 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23   EXCLUSIVE..*/.#
e050: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
e060: 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31  M_UNLOCK       1
e070: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e080: 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20  SHM_LOCK        
e090: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
e0a0: 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20  E_SHM_SHARED    
e0b0: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
e0c0: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
e0d0: 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41  E    8../*.** CA
e0e0: 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20  PI3REF: Maximum 
e0f0: 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a  xShmLock index.*
e100: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
e110: 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c  k method on [sql
e120: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
e130: 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a   may use values.
e140: 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ** between 0 and
e150: 20 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e   this upper boun
e160: 64 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74  d as its "offset
e170: 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  " argument..** T
e180: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77  he SQLite core w
e190: 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70  ill never attemp
e1a0: 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20  t to acquire or 
e1b0: 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63  release a.** loc
e1c0: 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69  k outside of thi
e1d0: 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69  s range.*/.#defi
e1e0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c  ne SQLITE_SHM_NL
e1f0: 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f  OCK        8.../
e200: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
e210: 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51  nitialize The SQ
e220: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
e230: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
e240: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
e250: 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73  tine initializes
e260: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c   the.** SQLite l
e270: 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71  ibrary.  ^The sq
e280: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
e290: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c   routine.** deal
e2a0: 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f  locates any reso
e2b0: 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20  urces that were 
e2c0: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
e2d0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e2e0: 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  )..** These rout
e2f0: 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65  ines are designe
e300: 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63  d to aid in proc
e310: 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ess initializati
e320: 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f  on and.** shutdo
e330: 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73  wn on embedded s
e340: 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61  ystems.  Worksta
e350: 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  tion application
e360: 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74  s using.** SQLit
e370: 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f  e normally do no
e380: 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65  t need to invoke
e390: 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65   either of these
e3a0: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
e3b0: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   A call to sqlit
e3c0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
e3d0: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
e3e0: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a  " call if it is.
e3f0: 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  ** the first tim
e400: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
e410: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
e420: 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66  d during the lif
e430: 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20  etime of.** the 
e440: 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69  process, or if i
e450: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74  t is the first t
e460: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
e470: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
e480: 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  ked.** following
e490: 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   a call to sqlit
e4a0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
e4b0: 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74  ^(Only an effect
e4c0: 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73  ive call.** of s
e4d0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
e4e0: 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69  e() does any ini
e4f0: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c  tialization.  Al
e500: 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a  l other calls.**
e510: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
e520: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20  -ops.)^.**.** A 
e530: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
e540: 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e  shutdown() is an
e550: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
e560: 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  l if it is the f
e570: 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  irst.** call to 
e580: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
e590: 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73  () since the las
e5a0: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
e5b0: 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a  lize().  ^(Only.
e5c0: 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ** an effective 
e5d0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
e5e0: 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20  shutdown() does 
e5f0: 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61  any deinitializa
e600: 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68  tion..** All oth
e610: 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74  er valid calls t
e620: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
e630: 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73  wn() are harmles
e640: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
e650: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
e660: 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72  itialize() inter
e670: 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61  face is threadsa
e680: 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f  fe, but sqlite3_
e690: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73  shutdown().** is
e6a0: 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74   not.  The sqlit
e6b0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e  e3_shutdown() in
e6c0: 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c  terface must onl
e6d0: 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  y be called from
e6e0: 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72   a.** single thr
e6f0: 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b  ead.  All open [
e700: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
e710: 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c  ions] must be cl
e720: 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20  osed and all.** 
e730: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73  other SQLite res
e740: 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64  ources must be d
e750: 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72  eallocated prior
e760: 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20   to invoking.** 
e770: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
e780: 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20  ()..**.** Among 
e790: 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73  other things, ^s
e7a0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
e7b0: 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a  e() will invoke.
e7c0: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
e7d0: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79  it().  Similarly
e7e0: 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64  , ^sqlite3_shutd
e7f0: 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e  own().** will in
e800: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f  voke sqlite3_os_
e810: 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  end()..**.** ^Th
e820: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
e830: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72  lize() routine r
e840: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
e850: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a  K] on success..*
e860: 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72  * ^If for some r
e870: 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69  eason, sqlite3_i
e880: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75  nitialize() is u
e890: 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c  nable to initial
e8a0: 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61  ize.** the libra
e8b0: 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69  ry (perhaps it i
e8c0: 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
e8d0: 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65  cate a needed re
e8e0: 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61  source such.** a
e8f0: 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65  s a mutex) it re
e900: 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20  turns an [error 
e910: 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e  code] other than
e920: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
e930: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
e940: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
e950: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
e960: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61  internally by ma
e970: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ny other.** SQLi
e980: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f  te interfaces so
e990: 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61   that an applica
e9a0: 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65  tion usually doe
e9b0: 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a  s not need to.**
e9c0: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
e9d0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
e9e0: 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d  ectly.  For exam
e9f0: 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ple, [sqlite3_op
ea00: 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73  en()].** calls s
ea10: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
ea20: 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74  e() so the SQLit
ea30: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62  e library will b
ea40: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
ea50: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77  ** initialized w
ea60: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  hen [sqlite3_ope
ea70: 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69  n()] is called i
ea80: 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20  f it has not be 
ea90: 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61  initialized.** a
eaa0: 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65  lready.  ^Howeve
eab0: 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  r, if SQLite is 
eac0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
ead0: 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
eae0: 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70  UTOINIT].** comp
eaf0: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c  ile-time option,
eb00: 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61   then the automa
eb10: 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  tic calls to sql
eb20: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
eb30: 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64  ).** are omitted
eb40: 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
eb50: 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73  tion must call s
eb60: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
eb70: 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  e() directly.** 
eb80: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
eb90: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
eba0: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20  interface.  For 
ebb0: 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c  maximum portabil
ebc0: 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65  ity,.** it is re
ebd0: 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
ebe0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61  pplications alwa
ebf0: 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ys invoke sqlite
ec00: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
ec10: 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72  * directly prior
ec20: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
ec30: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
ec40: 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65  face.  Future re
ec50: 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c  leases.** of SQL
ec60: 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20  ite may require 
ec70: 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20  this.  In other 
ec80: 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76  words, the behav
ec90: 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a  ior exhibited.**
eca0: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
ecb0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
ecc0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
ecd0: 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d  NIT] might becom
ece0: 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74  e the.** default
ecf0: 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d   behavior in som
ed00: 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
ed10: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
ed20: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73  * The sqlite3_os
ed30: 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20  _init() routine 
ed40: 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73  does operating-s
ed50: 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a  ystem specific.*
ed60: 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  * initialization
ed70: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c   of the SQLite l
ed80: 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c  ibrary.  The sql
ed90: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
eda0: 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20   routine undoes 
edb0: 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71  the effect of sq
edc0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
edd0: 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a    Typical tasks.
ede0: 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  ** performed by 
edf0: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69  these routines i
ee00: 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f  nclude allocatio
ee10: 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f  n or deallocatio
ee20: 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72  n.** of static r
ee30: 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61  esources, initia
ee40: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62  lization of glob
ee50: 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a  al variables,.**
ee60: 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65   setting up a de
ee70: 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
ee80: 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73  fs] module, or s
ee90: 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64  etting up.** a d
eea0: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
eeb0: 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69  tion using [sqli
eec0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a  te3_config()]..*
eed0: 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
eee0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
eef0: 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  r invoke either 
ef00: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
ef10: 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
ef20: 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c  os_end() directl
ef30: 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  y.  The applicat
ef40: 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20  ion should only 
ef50: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
ef60: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
ef70: 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nd sqlite3_shutd
ef80: 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69  own().  The sqli
ef90: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
efa0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61   interface is ca
efb0: 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  lled automatical
efc0: 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ly by sqlite3_in
efd0: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a  itialize() and.*
efe0: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  * sqlite3_os_end
eff0: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20  () is called by 
f000: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f010: 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65  ().  Appropriate
f020: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
f030: 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  ons for sqlite3_
f040: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
f050: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
f060: 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f  * are built into
f070: 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20   SQLite when it 
f080: 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  is compiled for 
f090: 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f  Unix, Windows, o
f0a0: 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20  r OS/2..** When 
f0b0: 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c  [custom builds |
f0c0: 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72   built for other
f0d0: 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28   platforms].** (
f0e0: 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
f0f0: 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f  E_OS_OTHER=1] co
f100: 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
f110: 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63  tion) the applic
f120: 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c  ation must suppl
f130: 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70  y a suitable imp
f140: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  lementation for.
f150: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
f160: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
f170: 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61  _os_end().  An a
f180: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c  pplication-suppl
f190: 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ied.** implement
f1a0: 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
f1b0: 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71  _os_init() or sq
f1c0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
f1d0: 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53  * must return [S
f1e0: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
f1f0: 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74  cess and some ot
f200: 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  her [error code]
f210: 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65   upon.** failure
f220: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
f230: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64  _initialize(void
f240: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  );.int sqlite3_s
f250: 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69  hutdown(void);.i
f260: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  nt sqlite3_os_in
f270: 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  it(void);.int sq
f280: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69  lite3_os_end(voi
f290: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
f2a0: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67  REF: Configuring
f2b0: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
f2c0: 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ary.**.** The sq
f2d0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
f2e0: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
f2f0: 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20   to make global 
f300: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
f310: 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69   changes to SQLi
f320: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74  te in order to t
f330: 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68  une SQLite to th
f340: 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
f350: 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
f360: 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66  cation.  The def
f370: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
f380: 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  on is recommende
f390: 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70  d for most.** ap
f3a0: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73  plications and s
f3b0: 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  o this routine i
f3c0: 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65  s usually not ne
f3d0: 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a  cessary.  It is.
f3e0: 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  ** provided to s
f3f0: 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c  upport rare appl
f400: 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e  ications with un
f410: 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a  usual needs..**.
f420: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
f430: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
f440: 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  e is not threads
f450: 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63  afe.  The applic
f460: 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  ation.** must in
f470: 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68  sure that no oth
f480: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
f490: 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64  aces are invoked
f4a0: 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72   by other.** thr
f4b0: 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74  eads while sqlit
f4c0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72  e3_config() is r
f4d0: 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72  unning.  Further
f4e0: 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f  more, sqlite3_co
f4f0: 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e  nfig().** may on
f500: 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72  ly be invoked pr
f510: 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69  ior to library i
f520: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73  nitialization us
f530: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
f540: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72  initialize()] or
f550: 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20   after shutdown 
f560: 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  by [sqlite3_shut
f570: 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20  down()]..** ^If 
f580: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
f590: 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72   is called after
f5a0: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
f5b0: 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f  lize()] and befo
f5c0: 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  re.** [sqlite3_s
f5d0: 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20  hutdown()] then 
f5e0: 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53  it will return S
f5f0: 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a  QLITE_MISUSE..**
f600: 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20   Note, however, 
f610: 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f  that ^sqlite3_co
f620: 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61  nfig() can be ca
f630: 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  lled as part of 
f640: 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
f650: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c  ation of an appl
f660: 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
f670: 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74  [sqlite3_os_init
f680: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ()]..**.** The f
f690: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
f6a0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
f6b0: 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  ) is an integer.
f6c0: 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  ** [configuratio
f6d0: 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64  n option] that d
f6e0: 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61  etermines.** wha
f6f0: 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51  t property of SQ
f700: 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f  Lite is to be co
f710: 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65  nfigured.  Subse
f720: 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a  quent arguments.
f730: 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ** vary dependin
f740: 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67  g on the [config
f750: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a  uration option].
f760: 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
f770: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
f780: 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72  ^When a configur
f790: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
f7a0: 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  set, sqlite3_con
f7b0: 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53  fig() returns [S
f7c0: 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49  QLITE_OK]..** ^I
f7d0: 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20  f the option is 
f7e0: 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74  unknown or SQLit
f7f0: 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73  e is unable to s
f800: 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a  et the option.**
f810: 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
f820: 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  ne returns a non
f830: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
f840: 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  e]..*/.int sqlit
f850: 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e  e3_config(int, .
f860: 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
f870: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20  3REF: Configure 
f880: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
f890: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ions.**.** The s
f8a0: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
f8b0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
f8c0: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e  used to make con
f8d0: 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
f8e0: 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61  anges to a [data
f8f0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
f900: 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  .  The interface
f910: 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a   is similar to.*
f920: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
f930: 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74  g()] except that
f940: 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70   the changes app
f950: 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a  ly to a single.*
f960: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
f970: 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69  ection] (specifi
f980: 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
f990: 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a  argument)..**.**
f9a0: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
f9b0: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
f9c0: 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e  db_config(D,V,..
f9d0: 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53  .)  is the.** [S
f9e0: 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
f9f0: 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69  OOKASIDE | confi
fa00: 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d  guration verb] -
fa10: 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
fa20: 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61   .** that indica
fa30: 74 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20  tes what aspect 
fa40: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
fa50: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
fa60: 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64  being configured
fa70: 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20  ..** Subsequent 
fa80: 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64  arguments vary d
fa90: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
faa0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
fab0: 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73  rb..**.** ^Calls
fac0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
fad0: 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53  onfig() return S
fae0: 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20  QLITE_OK if and 
faf0: 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63  only if.** the c
fb00: 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65  all is considere
fb10: 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f  d successful..*/
fb20: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f  .int sqlite3_db_
fb30: 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c  config(sqlite3*,
fb40: 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a   int op, ...);..
fb50: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
fb60: 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
fb70: 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a  n Routines.**.**
fb80: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
fb90: 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  this object defi
fba0: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
fbb0: 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65  e between SQLite
fbc0: 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65  .** and low-leve
fbd0: 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
fbe0: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ion routines..**
fbf0: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
fc00: 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20  is used in only 
fc10: 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65  one place in the
fc20: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
fc30: 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  e..** A pointer 
fc40: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
fc50: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  f this object is
fc60: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
fc70: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
fc80: 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20  fig()] when the 
fc90: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
fca0: 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49  tion is.** [SQLI
fcb0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
fcc0: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
fcd0: 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20  FIG_GETMALLOC]. 
fce0: 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67   .** By creating
fcf0: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
fd00: 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61  this object.** a
fd10: 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  nd passing it to
fd20: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
fd30: 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
fd40: 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72  _MALLOC]).** dur
fd50: 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
fd60: 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  n, an applicatio
fd70: 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e  n can specify an
fd80: 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
fd90: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
fda0: 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20  n subsystem for 
fdb0: 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f  SQLite to use fo
fdc0: 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20  r all of its.** 
fdd0: 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e  dynamic memory n
fde0: 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  eeds..**.** Note
fdf0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d   that SQLite com
fe00: 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20  es with several 
fe10: 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79  [built-in memory
fe20: 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20   allocators].** 
fe30: 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74  that are perfect
fe40: 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20  ly adequate for 
fe50: 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67  the overwhelming
fe60: 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70   majority of app
fe70: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64  lications.** and
fe80: 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63   that this objec
fe90: 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c  t is only useful
fea0: 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72   to a tiny minor
feb0: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
fec0: 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63  ons.** with spec
fed0: 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61  ialized memory a
fee0: 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72  llocation requir
fef0: 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62  ements.  This ob
ff00: 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20  ject is.** also 
ff10: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
ff20: 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e  ing of SQLite in
ff30: 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66   order to specif
ff40: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
ff50: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
ff60: 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61  ator that simula
ff70: 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f  tes memory out-o
ff80: 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69  f-memory conditi
ff90: 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20  ons in.** order 
ffa0: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53  to verify that S
ffb0: 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67  QLite recovers g
ffc0: 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73  racefully from s
ffd0: 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e  uch.** condition
ffe0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61  s..**.** The xMa
fff0: 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20  lloc, xRealloc, 
10000 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64  and xFree method
10010 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  s must work like
10020 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
10030 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  , realloc() and 
10040 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73  free() functions
10050 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
10060 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
10070 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
10080 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63  ees that the sec
10090 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
100a0 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61  ** xRealloc is a
100b0 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65  lways a value re
100c0 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f  turned by a prio
100d0 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64  r call to xRound
100e0 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20  up..**.** xSize 
100f0 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68  should return th
10100 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
10110 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   of a memory all
10120 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69  ocation.** previ
10130 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
10140 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78  rom xMalloc or x
10150 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c  Realloc.  The al
10160 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20  located size.** 
10170 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61  is always at lea
10180 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65  st as big as the
10190 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20   requested size 
101a0 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
101b0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f  r..**.** The xRo
101c0 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74  undup method ret
101d0 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20  urns what would 
101e0 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  be the allocated
101f0 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65   size of.** a me
10200 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10210 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c  given a particul
10220 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  ar requested siz
10230 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a  e.  Most memory.
10240 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  ** allocators ro
10250 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c  und up memory al
10260 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61  locations at lea
10270 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d  st to the next m
10280 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e  ultiple.** of 8.
10290 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72    Some allocator
102a0 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20  s round up to a 
102b0 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  larger multiple 
102c0 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66  or to a power of
102d0 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d   2..** Every mem
102e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
102f0 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e  equest coming in
10300 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65   through [sqlite
10310 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f  3_malloc()].** o
10320 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
10330 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c  oc()] first call
10340 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20  s xRoundup.  If 
10350 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73  xRoundup returns
10360 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75   0, .** that cau
10370 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ses the correspo
10380 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c  nding memory all
10390 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e  ocation to fail.
103a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74  .**.** The xInit
103b0 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69   method initiali
103c0 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  zes the memory a
103d0 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20  llocator.  (For 
103e0 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d  example,.** it m
103f0 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e  ight allocate an
10400 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65  y require mutexe
10410 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20  s or initialize 
10420 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a  internal data.**
10430 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68   structures.  Th
10440 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  e xShutdown meth
10450 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69  od is invoked (i
10460 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a  ndirectly) by.**
10470 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
10480 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64  wn()] and should
10490 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20   deallocate any 
104a0 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72  resources acquir
104b0 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20  ed.** by xInit. 
104c0 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f   The pAppData po
104d0 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73  inter is used as
104e0 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
104f0 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20  ter to.** xInit 
10500 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a  and xShutdown..*
10510 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64  *.** SQLite hold
10520 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
10530 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
10540 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74  R] mutex when it
10550 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20   invokes.** the 
10560 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f  xInit method, so
10570 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
10580 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68  d need not be th
10590 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a  readsafe.  The.*
105a0 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  * xShutdown meth
105b0 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65  od is only calle
105c0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
105d0 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69  shutdown()] so i
105e0 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65  t does.** not ne
105f0 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73  ed to be threads
10600 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72  afe either.  For
10610 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f   all other metho
10620 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f  ds, SQLite.** ho
10630 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
10640 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d  MUTEX_STATIC_MEM
10650 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20  ] mutex as long 
10660 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  as the.** [SQLIT
10670 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
10680 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  US] configuratio
10690 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e  n option is turn
106a0 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20  ed on (which.** 
106b0 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74  it is by default
106c0 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74  ) and so the met
106d0 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74  hods are automat
106e0 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65  ically serialize
106f0 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69  d..** However, i
10700 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
10710 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64  _MEMSTATUS] is d
10720 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68  isabled, then th
10730 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f  e other.** metho
10740 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  ds must be threa
10750 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61  dsafe or else ma
10760 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72  ke their own arr
10770 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a  angements for.**
10780 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a   serialization..
10790 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  **.** SQLite wil
107a0 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78  l never invoke x
107b0 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e  Init() more than
107c0 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e   once without an
107d0 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20   intervening.** 
107e0 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77  call to xShutdow
107f0 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n()..*/.typedef 
10800 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
10810 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  em_methods sqlit
10820 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a  e3_mem_methods;.
10830 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
10840 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76  em_methods {.  v
10850 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28  oid *(*xMalloc)(
10860 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a  int);         /*
10870 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
10880 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  on function */. 
10890 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76   void (*xFree)(v
108a0 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
108b0 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20  /* Free a prior 
108c0 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
108d0 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63  void *(*xRealloc
108e0 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f  )(void*,int);  /
108f0 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f  * Resize an allo
10900 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
10910 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b  (*xSize)(void*);
10920 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65             /* Re
10930 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  turn the size of
10940 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
10950 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64  /.  int (*xRound
10960 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  up)(int);       
10970 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72     /* Round up r
10980 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61  equest size to a
10990 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a  llocation size *
109a0 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29  /.  int (*xInit)
109b0 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
109c0 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65     /* Initialize
109d0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
109e0 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
109f0 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69  (*xShutdown)(voi
10a00 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69  d*);      /* Dei
10a10 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
10a20 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
10a30 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
10a40 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  ta;             
10a50 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74     /* Argument t
10a60 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53  o xInit() and xS
10a70 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a  hutdown() */.};.
10a80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10a90 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
10aa0 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ptions.** KEYWOR
10ab0 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69  DS: {configurati
10ac0 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a  on option}.**.**
10ad0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
10ae0 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
10af0 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
10b00 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
10b10 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
10b20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
10b30 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
10b40 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
10b50 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
10b60 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
10b70 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10b80 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
10b90 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
10ba0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
10bb0 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
10bc0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
10bd0 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
10be0 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
10bf0 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
10c00 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
10c10 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
10c20 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  3_config()] to m
10c30 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
10c40 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
10c50 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
10c60 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
10c70 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
10c80 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
10c90 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
10ca0 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
10cb0 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
10cc0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10cd0 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
10ce0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
10cf0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
10d00 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74  NGLETHREAD]] <dt
10d10 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
10d20 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e  INGLETHREAD</dt>
10d30 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
10d40 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
10d50 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
10d60 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
10d70 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
10d80 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e  ing mode] to Sin
10d90 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  gle-thread.  In 
10da0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
10db0 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20  disables.** all 
10dc0 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74  mutexing and put
10dd0 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20  s SQLite into a 
10de0 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61  mode where it ca
10df0 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a  n only be used.*
10e00 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68  * by a single th
10e10 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69  read.   ^If SQLi
10e20 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
10e30 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
10e40 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
10e50 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
10e60 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
10e70 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
10e80 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
10e90 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ble to change th
10ea0 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
10eb0 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61  e] from its defa
10ec0 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  ult.** value of 
10ed0 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e  Single-thread an
10ee0 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d so [sqlite3_co
10ef0 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
10f00 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urn .** [SQLITE_
10f10 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
10f20 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
10f30 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
10f40 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  READ.** configur
10f50 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
10f60 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
10f70 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
10f80 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  READ]] <dt>SQLIT
10f90 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
10fa0 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
10fb0 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
10fc0 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
10fd0 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
10fe0 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
10ff0 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
11000 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65  e] to Multi-thre
11010 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
11020 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
11030 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20  .** mutexing on 
11040 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11050 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
11060 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
11070 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61  bjects..** The a
11080 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65  pplication is re
11090 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65  sponsible for se
110a0 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73  rializing access
110b0 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65   to.** [database
110c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
110d0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
110e0 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74  ements].  But ot
110f0 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61  her mutexes.** a
11100 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68  re enabled so th
11110 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  at SQLite will b
11120 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e  e safe to use in
11130 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
11140 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  d.** environment
11150 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74   as long as no t
11160 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d  wo threads attem
11170 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  pt to use the sa
11180 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  me.** [database 
11190 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74  connection] at t
111a0 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e  he same time.  ^
111b0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
111c0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
111d0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
111e0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
111f0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
11200 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
11210 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
11220 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
11230 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65  t the Multi-thre
11240 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
11250 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
11260 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
11270 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
11280 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
11290 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
112a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
112b0 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75  TITHREAD configu
112c0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
112d0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
112e0 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
112f0 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  IZED]] <dt>SQLIT
11300 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
11310 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ZED</dt>.** <dd>
11320 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
11330 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
11340 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
11350 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
11360 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
11370 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e  ] to Serialized.
11380 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
11390 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61   this option ena
113a0 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
113b0 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  xes including th
113c0 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d  e recursive.** m
113d0 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62  utexes on [datab
113e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
113f0 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
11400 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
11410 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64  ..** In this mod
11420 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20  e (which is the 
11430 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c  default when SQL
11440 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
11450 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  with.** [SQLITE_
11460 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74  THREADSAFE=1]) t
11470 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
11480 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65  y will itself se
11490 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a  rialize access.*
114a0 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63  * to [database c
114b0 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
114c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
114d0 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68  ents] so that th
114e0 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  e.** application
114f0 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20   is free to use 
11500 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
11510 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
11520 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70  r the.** same [p
11530 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
11540 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20  t] in different 
11550 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
11560 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66  ame time..** ^If
11570 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
11580 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
11590 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
115a0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
115b0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
115c0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
115d0 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
115e0 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
115f0 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b  the Serialized [
11600 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
11610 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
11620 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
11630 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
11640 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
11650 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
11660 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
11670 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ZED configuratio
11680 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
11690 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
116a0 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  NFIG_MALLOC]] <d
116b0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
116c0 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
116d0 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
116e0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
116f0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
11700 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
11710 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
11720 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
11730 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
11740 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75  cture.  The argu
11750 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a  ment specifies.*
11760 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  * alternative lo
11770 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
11780 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
11790 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e  es to be used in
117a0 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65   place of.** the
117b0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
117c0 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c  on routines buil
117d0 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e  t into SQLite.)^
117e0 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a   ^SQLite makes.*
117f0 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  * its own privat
11800 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f  e copy of the co
11810 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71  ntent of the [sq
11820 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
11830 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20  s] structure.** 
11840 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69  before the [sqli
11850 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  te3_config()] ca
11860 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e  ll returns.</dd>
11870 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11880 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
11890 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
118a0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f  NFIG_GETMALLOC</
118b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
118c0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
118d0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
118e0 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
118f0 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
11900 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
11910 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
11920 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
11930 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
11940 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
11950 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
11960 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
11970 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f  tly defined memo
11980 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
11990 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
119a0 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
119b0 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
119c0 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d   the default mem
119d0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
119e0 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
119f0 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73  a wrapper that s
11a00 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72  imulations memor
11a10 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
11a20 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b  lure or.** track
11a30 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20  s memory usage, 
11a40 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64  for example. </d
11a50 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
11a60 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
11a70 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  US]] <dt>SQLITE_
11a80 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
11a90 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
11aa0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
11ab0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
11ac0 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e   of type int, in
11ad0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 0a  terpreted as a .
11ae0 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63  ** boolean, whic
11af0 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  h enables or dis
11b00 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63  ables the collec
11b10 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61  tion of memory a
11b20 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74  llocation .** st
11b30 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e  atistics. ^(When
11b40 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11b50 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
11b60 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20  e disabled, the 
11b70 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51  .** following SQ
11b80 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
11b90 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61  become non-opera
11ba0 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c  tional:.**   <ul
11bb0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  >.**   <li> [sql
11bc0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
11bd0 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
11be0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
11bf0 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20  ghwater()].**   
11c00 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f  <li> [sqlite3_so
11c10 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
11c20 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
11c30 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a  lite3_status()].
11c40 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20  **   </ul>)^.** 
11c50 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69  ^Memory allocati
11c60 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
11c70 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66  e enabled by def
11c80 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69  ault unless SQLi
11c90 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  te is.** compile
11ca0 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44  d with [SQLITE_D
11cb0 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53  EFAULT_MEMSTATUS
11cc0 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73  ]=0 in which cas
11cd0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
11ce0 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
11cf0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
11d00 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f  y default..** </
11d10 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
11d20 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
11d30 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  H]] <dt>SQLITE_C
11d40 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64  ONFIG_SCRATCH</d
11d50 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
11d60 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
11d70 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
11d80 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
11d90 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
11da0 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  .** scratch memo
11db0 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74  ry.  There are t
11dc0 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
11dd0 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d   A pointer an 8-
11de0 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20  byte.** aligned 
11df0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72  memory buffer fr
11e00 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72  om which the scr
11e10 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  atch allocations
11e20 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77   will be.** draw
11e30 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  n, the size of e
11e40 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  ach scratch allo
11e50 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20  cation (sz),.** 
11e60 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  and the maximum 
11e70 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63  number of scratc
11e80 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e  h allocations (N
11e90 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72  ).  The sz.** ar
11ea0 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
11eb0 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e   multiple of 16.
11ec0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
11ed0 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
11ee0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38   pointer to an 8
11ef0 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75  -byte aligned bu
11f00 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  ffer.** of at le
11f10 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
11f20 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51  f memory..** ^SQ
11f30 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f  Lite will use no
11f40 20 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73   more than two s
11f50 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70  cratch buffers p
11f60 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a  er thread.  So.*
11f70 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65  * N should be se
11f80 74 20 74 6f 20 74 77 69 63 65 20 74 68 65 20 65  t to twice the e
11f90 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20  xpected maximum 
11fa0 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64  number of thread
11fb0 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  s..** ^SQLite wi
11fc0 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 69 72 65  ll never require
11fd0 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65   a scratch buffe
11fe0 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74  r that is more t
11ff0 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74  han 6.** times t
12000 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
12010 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74   size. ^If SQLit
12020 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64  e needs needs ad
12030 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61  ditional.** scra
12040 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e  tch memory beyon
12050 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
12060 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69  ed by this confi
12070 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c  guration option,
12080 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74   then .** [sqlit
12090 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c  e3_malloc()] wil
120a0 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  l be used to obt
120b0 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e  ain the memory n
120c0 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  eeded.</dd>.**.*
120d0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
120e0 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64  G_PAGECACHE]] <d
120f0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12100 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a  PAGECACHE</dt>.*
12110 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
12120 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
12130 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
12140 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
12150 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
12160 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
12170 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65  e cache with the
12180 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61   default page ca
12190 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
121a0 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f  on.  .** This co
121b0 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75  nfiguration shou
121c0 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69  ld not be used i
121d0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
121e0 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20  -define page.** 
121f0 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
12200 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75  tion is loaded u
12210 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f  sing the SQLITE_
12220 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f  CONFIG_PCACHE2 o
12230 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20  ption..** There 
12240 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
12250 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
12260 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  on: A pointer to
12270 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a   8-byte aligned.
12280 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73  ** memory, the s
12290 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65  ize of each page
122a0 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e   buffer (sz), an
122b0 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
122c0 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68  pages (N)..** Th
122d0 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68  e sz argument sh
122e0 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65  ould be the size
122f0 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
12300 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a  database page.**
12310 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f   (a power of two
12320 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64   between 512 and
12330 20 33 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c   32768) plus a l
12340 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20  ittle extra for 
12350 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61  each.** page hea
12360 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20  der.  ^The page 
12370 68 65 61 64 65 72 20 73 69 7a 65 20 69 73 20 32  header size is 2
12380 30 20 74 6f 20 34 30 20 62 79 74 65 73 20 64 65  0 to 40 bytes de
12390 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68  pending on.** th
123a0 65 20 68 6f 73 74 20 61 72 63 68 69 74 65 63 74  e host architect
123b0 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72  ure.  ^It is har
123c0 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f  mless, apart fro
123d0 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d  m the wasted mem
123e0 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20  ory,.** to make 
123f0 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20  sz a little too 
12400 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69 72 73  large.  The firs
12410 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68  t.** argument sh
12420 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e  ould point to an
12430 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61   allocation of a
12440 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
12450 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
12460 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
12470 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
12480 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72  vided by the fir
12490 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
124a0 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65  atisfy its.** me
124b0 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74  mory needs for t
124c0 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73  he first N pages
124d0 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f   that it adds to
124e0 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64   cache.  ^If add
124f0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20  itional.** page 
12500 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20  cache memory is 
12510 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68  needed beyond wh
12520 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
12530 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74  y this option, t
12540 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f  hen.** SQLite go
12550 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  es to [sqlite3_m
12560 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65  alloc()] for the
12570 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72   additional stor
12580 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68  age space..** Th
12590 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65  e pointer in the
125a0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
125b0 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e  must.** be align
125c0 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
125d0 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73  boundary or subs
125e0 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20  equent behavior 
125f0 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  of SQLite.** wil
12600 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c  l be undefined.<
12610 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12620 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d  ITE_CONFIG_HEAP]
12630 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12640 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a  FIG_HEAP</dt>.**
12650 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
12660 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
12670 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
12680 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
12690 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20  will use.** for 
126a0 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d  all of its dynam
126b0 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ic memory alloca
126c0 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e  tion needs beyon
126d0 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64  d those provided
126e0 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49  .** for by [SQLI
126f0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
12700 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43  H] and [SQLITE_C
12710 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
12720 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  ..** There are t
12730 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
12740 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  An 8-byte aligne
12750 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  d pointer to the
12760 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20   memory,.** the 
12770 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
12780 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75  in the memory bu
12790 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69  ffer, and the mi
127a0 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
127b0 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68   size..** ^If th
127c0 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
127d0 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
127e0 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ter) is NULL, th
127f0 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74  en SQLite revert
12800 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74  s.** to using it
12810 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  s default memory
12820 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20   allocator (the 
12830 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
12840 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c  implementation),
12850 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20  .** undoing any 
12860 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e  prior invocation
12870 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   of [SQLITE_CONF
12880 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66  IG_MALLOC].  ^If
12890 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70   the.** memory p
128a0 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
128b0 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53  LL and either [S
128c0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
128d0 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  SYS3] or.** [SQL
128e0 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
128f0 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c  S5] are defined,
12900 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e   then the altern
12910 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ative memory.** 
12920 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67  allocator is eng
12930 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61  aged to handle a
12940 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65  ll of SQLites me
12950 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12960 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69  needs..** The fi
12970 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
12980 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
12990 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
129a0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a   to an 8-byte.**
129b0 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62   boundary or sub
129c0 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
129d0 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20   of SQLite will 
129e0 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  be undefined..**
129f0 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   The minimum all
12a00 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20  ocation size is 
12a10 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e  capped at 2**12.
12a20 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75   Reasonable valu
12a30 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69  es.** for the mi
12a40 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
12a50 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74   size are 2**5 t
12a60 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64  hrough 2**8.</dd
12a70 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12a80 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20  _CONFIG_MUTEX]] 
12a90 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
12aa0 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  G_MUTEX</dt>.** 
12ab0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
12ac0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
12ad0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
12ae0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
12af0 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
12b00 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
12b10 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
12b20 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61  tructure.  The a
12b30 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
12b40 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65  s.** alternative
12b50 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78   low-level mutex
12b60 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
12b70 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a  used in place.**
12b80 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69   the mutex routi
12b90 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
12ba0 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74  QLite.)^  ^SQLit
12bb0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
12bc0 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  f the.** content
12bd0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
12be0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
12bf0 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65  structure before
12c00 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
12c10 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
12c20 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20  )] returns. ^If 
12c30 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
12c40 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
12c50 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
12c60 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
12c70 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
12c80 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
12c90 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
12ca0 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
12cb0 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
12cc0 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
12cd0 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
12ce0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
12cf0 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
12d00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
12d10 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
12d20 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
12d30 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
12d40 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
12d50 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12d60 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74  G_GETMUTEX]] <dt
12d70 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
12d80 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  ETMUTEX</dt>.** 
12d90 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
12da0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
12db0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
12dc0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
12dd0 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
12de0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
12df0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
12e00 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a  tructure.  The.*
12e10 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  * [sqlite3_mutex
12e20 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
12e30 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
12e40 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
12e50 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65  tly defined mute
12e60 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  x routines.)^.**
12e70 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
12e80 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
12e90 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
12ea0 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f   mutex allocatio
12eb0 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
12ec0 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65  th a wrapper use
12ed0 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78  d to track mutex
12ee0 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f   usage for perfo
12ef0 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c  rmance.** profil
12f00 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20  ing or testing, 
12f10 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e  for example.   ^
12f20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
12f30 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
12f40 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
12f50 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
12f60 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
12f70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
12f80 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
12f90 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
12fa0 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
12fb0 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
12fc0 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
12fd0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
12fe0 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
12ff0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13000 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  GETMUTEX configu
13010 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
13020 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
13030 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
13040 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
13050 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
13060 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
13070 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
13080 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
13090 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
130a0 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74   two arguments t
130b0 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
130c0 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d  e default.** mem
130d0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
130e0 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  or the lookaside
130f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
13100 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61  r on each.** [da
13110 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13120 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61  n].  The first a
13130 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
13140 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
13150 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
13160 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63  slot and the sec
13170 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ond is the numbe
13180 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c  r of.** slots al
13190 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20  located to each 
131a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
131b0 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f  ion.)^  ^(This o
131c0 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
131d0 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e  * <i>default</i>
131e0 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e   lookaside size.
131f0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43   The [SQLITE_DBC
13200 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
13210 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c  .** verb to [sql
13220 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
13230 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  ] can be used to
13240 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
13250 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75  aside.** configu
13260 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69  ration on indivi
13270 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  dual connections
13280 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
13290 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
132a0 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51  PCACHE2]] <dt>SQ
132b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
132c0 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HE2</dt>.** <dd>
132d0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
132e0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
132f0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
13300 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  a pointer to.** 
13310 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
13320 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
13330 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
13340 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
13350 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20  interface.** to 
13360 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61  a custom page ca
13370 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
13380 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  on.)^  ^SQLite m
13390 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
133a0 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64  he.** object and
133b0 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67   uses it for pag
133c0 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61  e cache memory a
133d0 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e  llocations.</dd>
133e0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
133f0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
13400 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  2]] <dt>SQLITE_C
13410 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
13420 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
13430 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
13440 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
13450 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
13460 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
13470 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
13480 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
13490 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73  .  SQLite copies
134a0 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a   of the current.
134b0 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  ** page cache im
134c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74  plementation int
134d0 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e  o that object.)^
134e0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
134f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
13500 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13510 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a  NFIG_LOG</dt>.**
13520 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45   <dd> The SQLITE
13530 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
13540 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  on is used to co
13550 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c 69  nfigure the SQLi
13560 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72  te.** global [er
13570 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54  ror log]..** (^T
13580 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
13590 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _LOG option take
135a0 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a  s two arguments:
135b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a   a pointer to a.
135c0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  ** function with
135d0 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72   a call signatur
135e0 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69  e of void(*)(voi
135f0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
13600 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70  r*), .** and a p
13610 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20  ointer to void. 
13620 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
13630 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
13640 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69  NULL, it is.** i
13650 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74  nvoked by [sqlit
13660 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f  e3_log()] to pro
13670 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e  cess each loggin
13680 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
13690 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f  e.** function po
136a0 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74  inter is NULL, t
136b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  he [sqlite3_log(
136c0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63  )] interface bec
136d0 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a  omes a no-op..**
136e0 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74   ^The void point
136f0 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73  er that is the s
13700 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
13710 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
13720 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64  LOG is.** passed
13730 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
13740 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
13750 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
13760 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
13770 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68  r.** function wh
13780 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63  enever that func
13790 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e  tion is invoked.
137a0 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61    ^The second pa
137b0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
137c0 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
137d0 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  n is a copy of t
137e0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
137f0 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73  er to the corres
13800 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  ponding.** [sqli
13810 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20  te3_log()] call 
13820 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20  and is intended 
13830 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20  to be a [result 
13840 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b  code] or an.** [
13850 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
13860 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69  code].  ^The thi
13870 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73  rd parameter pas
13880 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65  sed to the logge
13890 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73  r is.** log mess
138a0 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74  age after format
138b0 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65  ting via [sqlite
138c0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a  3_snprintf()]..*
138d0 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67  * The SQLite log
138e0 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69  ging interface i
138f0 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b  s not reentrant;
13900 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
13910 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64  tion.** supplied
13920 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
13930 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76  ion must not inv
13940 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  oke any SQLite i
13950 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20  nterface..** In 
13960 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
13970 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68   application, th
13980 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
13990 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
139a0 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  function must be
139b0 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64   threadsafe. </d
139c0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
139d0 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c  E_CONFIG_URI]] <
139e0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
139f0 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54 68 69  _URI.** <dd> Thi
13a00 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
13a10 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
13a20 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66   of type int. If
13a30 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a   non-zero, then.
13a40 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  ** URI handling 
13a50 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62  is globally enab
13a60 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61  led. If the para
13a70 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74  meter is zero, t
13a80 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  hen URI handling
13a90 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  .** is globally 
13aa0 64 69 73 61 62 6c 65 64 2e 20 49 66 20 55 52 49  disabled. If URI
13ab0 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
13ac0 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20 61  bally enabled, a
13ad0 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20  ll filenames.** 
13ae0 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74  passed to [sqlit
13af0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
13b00 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
13b10 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
13b20 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66  ()] or.** specif
13b30 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b  ied as part of [
13b40 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73  ATTACH] commands
13b50 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
13b60 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64   as URIs, regard
13b70 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68  less.** of wheth
13b80 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53  er or not the [S
13b90 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
13ba0 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e  flag is set when
13bb0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
13bc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
13bd0 70 65 6e 65 64 2e 20 49 66 20 69 74 20 69 73 20  pened. If it is 
13be0 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65  globally disable
13bf0 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65  d, filenames are
13c00 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72  .** only interpr
13c10 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20  eted as URIs if 
13c20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
13c30 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20  URI flag is set 
13c40 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61  when the.** data
13c50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
13c60 69 73 20 6f 70 65 6e 65 64 2e 20 42 79 20 64 65  is opened. By de
13c70 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c  fault, URI handl
13c80 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a  ing is globally.
13c90 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65  ** disabled. The
13ca0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d   default value m
13cb0 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79  ay be changed by
13cc0 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20   compiling with 
13cd0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  the.** [SQLITE_U
13ce0 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64  SE_URI] symbol d
13cf0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  efined..**.** [[
13d00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
13d10 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
13d20 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  N]] <dt>SQLITE_C
13d30 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
13d40 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64  NDEX_SCAN.** <dd
13d50 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  > This option ta
13d60 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74  kes a single int
13d70 65 67 65 72 20 61 72 67 75 6d 65 6e 74 20 77 68  eger argument wh
13d80 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65 74  ich is interpret
13d90 65 64 20 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65  ed as.** a boole
13da0 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65  an in order to e
13db0 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
13dc0 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65   the use of cove
13dd0 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72  ring indices for
13de0 0a 2a 2a 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  .** full table s
13df0 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72  cans in the quer
13e00 79 20 6f 70 74 69 6d 69 7a 65 72 2e 20 20 54 68  y optimizer.  Th
13e10 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
13e20 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a  g is determined.
13e30 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  ** by the [SQLIT
13e40 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47  E_ALLOW_COVERING
13e50 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d  _INDEX_SCAN] com
13e60 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
13e70 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20  , or is "on".** 
13e80 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d  if that compile-
13e90 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f  time option is o
13ea0 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61  mitted..** The a
13eb0 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c  bility to disabl
13ec0 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76  e the use of cov
13ed0 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f  ering indices fo
13ee0 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61  r full table sca
13ef0 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65  ns.** is because
13f00 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c   some incorrectl
13f10 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61  y coded legacy a
13f20 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68  pplications migh
13f30 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a  t malfunction.**
13f40 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 20 77 68 65   malfunction whe
13f50 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69  n the optimizati
13f60 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20  on is enabled.  
13f70 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62  Providing the ab
13f80 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61  ility to.** disa
13f90 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  ble the optimiza
13fa0 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20  tion allows the 
13fb0 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70 70  older, buggy app
13fc0 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f  lication code to
13fd0 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74   work.** without
13fe0 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74   change even wit
13ff0 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73  h newer versions
14000 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
14010 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14020 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c  G_PCACHE]] [[SQL
14030 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
14040 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  ACHE]].** <dt>SQ
14050 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
14060 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f  HE and SQLITE_CO
14070 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a  NFIG_GETPCACHE.*
14080 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74  * <dd> These opt
14090 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74  ions are obsolet
140a0 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74  e and should not
140b0 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77 20   be used by new 
140c0 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72  code..** They ar
140d0 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62  e retained for b
140e0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
140f0 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e  bility but are n
14100 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f  ow no-ops..** </
14110 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
14120 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
14130 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
14140 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a  _CONFIG_SQLLOG.*
14150 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
14160 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
14170 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69 73  ble if sqlite is
14180 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
14190 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
141a0 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65  ABLE_SQLLOG] pre
141b0 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  -processor macro
141c0 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69   defined. The fi
141d0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rst argument sho
141e0 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e  uld.** be a poin
141f0 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f  ter to a functio
14200 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a  n of type void(*
14210 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
14220 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e  ,const char*, in
14230 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  t)..** The secon
14240 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74  d should be of t
14250 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65  ype (void*). The
14260 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
14270 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62 72  oked by the libr
14280 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20  ary.** in three 
14290 73 65 70 61 72 61 74 65 20 63 69 72 63 75 6d 73  separate circums
142a0 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69  tances, identifi
142b0 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 20  ed by the value 
142c0 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a  passed as the.**
142d0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
142e0 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  r. If the fourth
142f0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c   parameter is 0,
14300 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
14310 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
14320 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
14330 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68  econd argument h
14340 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65  as just been ope
14350 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 61  ned. The third a
14360 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74  rgument.** point
14370 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f  s to a buffer co
14380 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d  ntaining the nam
14390 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61  e of the main da
143a0 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20  tabase file. If 
143b0 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
143c0 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68  rameter is 1, th
143d0 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  en the SQL state
143e0 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 74 68  ment that the th
143f0 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ird parameter.**
14400 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a   points to has j
14410 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 74 65  ust been execute
14420 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f  d. Or, if the fo
14430 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
14440 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  s 2, then.** the
14450 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e   connection bein
14460 67 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  g passed as the 
14470 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
14480 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64   is being closed
14490 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  . The.** third p
144a0 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 73 73  arameter is pass
144b0 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20  ed NULL In this 
144c0 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c  case.  An exampl
144d0 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a  e of using this.
144e0 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
144f0 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73   option can be s
14500 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74  een in the "test
14510 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63  _sqllog.c" sourc
14520 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65  e file in.** the
14530 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74   canonical SQLit
14540 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f  e source tree.</
14550 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
14560 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
14570 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  IZE]].** <dt>SQL
14580 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
14590 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 53 51 4c 49  SIZE.** <dd>SQLI
145a0 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
145b0 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34  IZE takes two 64
145c0 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28 73 71  -bit integer (sq
145d0 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c  lite3_int64) val
145e0 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  ues.** that are 
145f0 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70  the default mmap
14600 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65   size limit (the
14610 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67   default setting
14620 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20   for.** [PRAGMA 
14630 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20  mmap_size]) and 
14640 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f  the maximum allo
14650 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69  wed mmap size li
14660 6d 69 74 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61  mit..** The defa
14670 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20  ult setting can 
14680 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79  be overridden by
14690 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
146a0 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a  onnection using.
146b0 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b 50  ** either the [P
146c0 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
146d0 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20   command, or by 
146e0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51  using the.** [SQ
146f0 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
14700 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  SIZE] file contr
14710 6f 6c 2e 20 20 54 68 65 20 6d 61 78 69 6d 75 6d  ol.  The maximum
14720 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69   allowed mmap si
14730 7a 65 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20  ze.** cannot be 
14740 63 68 61 6e 67 65 64 20 61 74 20 72 75 6e 2d 74  changed at run-t
14750 69 6d 65 2e 20 20 4e 6f 72 20 6d 61 79 20 74 68  ime.  Nor may th
14760 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65  e maximum allowe
14770 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 65  d mmap size.** e
14780 78 63 65 65 64 20 74 68 65 20 63 6f 6d 70 69 6c  xceed the compil
14790 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d  e-time maximum m
147a0 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20  map size set by 
147b0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  the.** [SQLITE_M
147c0 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f  AX_MMAP_SIZE] co
147d0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
147e0 6e 2e 20 20 0a 2a 2a 20 49 66 20 65 69 74 68 65  n.  .** If eithe
147f0 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  r argument to th
14800 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67  is option is neg
14810 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74  ative, then that
14820 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
14830 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63  changed to its c
14840 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61  ompile-time defa
14850 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  ult..** </dl>.*/
14860 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14870 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
14880 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a  EAD  1  /* nil *
14890 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
148a0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
148b0 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20  EAD   2  /* nil 
148c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
148d0 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
148e0 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c  ZED    3  /* nil
148f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
14900 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
14910 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71          4  /* sq
14920 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
14930 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
14940 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
14950 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20  ALLOC     5  /* 
14960 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
14970 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
14980 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
14990 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f  RATCH       6  /
149a0 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
149b0 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
149c0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
149d0 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
149e0 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
149f0 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
14a00 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
14a10 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
14a20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
14a30 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
14a40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14a50 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
14a60 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
14a70 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
14a80 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
14a90 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
14aa0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
14ab0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
14ac0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
14ad0 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
14ae0 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
14af0 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
14b00 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51  /* previously SQ
14b10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e  LITE_CONFIG_CHUN
14b20 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20  KALLOC 12 which 
14b30 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a  is now unused. *
14b40 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  / .#define SQLIT
14b50 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
14b60 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74  DE    13  /* int
14b70 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
14b80 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14b90 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f  ACHE       14  /
14ba0 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69  * no-op */.#defi
14bb0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
14bc0 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35  _GETPCACHE    15
14bd0 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
14be0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
14bf0 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20  FIG_LOG         
14c00 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76   16  /* xFunc, v
14c10 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
14c20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
14c30 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f  I          17  /
14c40 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
14c50 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
14c60 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20  CACHE2      18  
14c70 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
14c80 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
14c90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
14ca0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20  NFIG_GETPCACHE2 
14cb0 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33    19  /* sqlite3
14cc0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
14cd0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
14ce0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
14cf0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32  ING_INDEX_SCAN 2
14d00 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  0  /* int */.#de
14d10 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
14d20 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20  IG_SQLLOG       
14d30 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20  21  /* xSqllog, 
14d40 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
14d50 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
14d60 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20  MAP_SIZE    22  
14d70 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  /* sqlite3_int64
14d80 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
14d90 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
14da0 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
14db0 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72  nection Configur
14dc0 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
14dd0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
14de0 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
14df0 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
14e00 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
14e10 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
14e20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
14e30 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
14e40 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
14e50 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
14e60 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
14e70 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
14e80 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
14e90 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
14ea0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
14eb0 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
14ec0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
14ed0 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
14ee0 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
14ef0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
14f00 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
14f10 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
14f20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
14f30 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
14f40 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
14f50 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68  all worked.  ^Th
14f60 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
14f70 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
14f80 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
14f90 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
14fa0 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
14fb0 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
14fc0 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
14fd0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
14fe0 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
14ff0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
15000 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
15010 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
15020 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
15030 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20  ion takes three 
15040 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
15050 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
15060 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f  ine the .** [loo
15070 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c  kaside memory al
15080 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75  locator] configu
15090 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b  ration for the [
150a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
150b0 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  ion]..** ^The fi
150c0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68  rst argument (th
150d0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
150e0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  r to [sqlite3_db
150f0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a  _config()] is a.
15100 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20  ** pointer to a 
15110 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f  memory buffer to
15120 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69   use for lookasi
15130 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54  de memory..** ^T
15140 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
15150 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49  t after the SQLI
15160 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
15170 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61  ASIDE verb.** ma
15180 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69  y be NULL in whi
15190 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77  ch case SQLite w
151a0 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  ill allocate the
151b0 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  .** lookaside bu
151c0 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e  ffer itself usin
151d0 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  g [sqlite3_mallo
151e0 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e  c()]. ^The secon
151f0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
15200 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
15210 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
15220 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74  er slot.  ^The t
15230 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
15240 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
15250 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69  * slots.  The si
15260 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
15270 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
15280 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67  gument must be g
15290 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f  reater than.** o
152a0 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70  r equal to the p
152b0 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65  roduct of the se
152c0 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61  cond and third a
152d0 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62  rguments.  The b
152e0 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65  uffer.** must be
152f0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
15300 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20  -byte boundary. 
15310 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20   ^If the second 
15320 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53  argument to.** S
15330 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
15340 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20  OOKASIDE is not 
15350 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c  a multiple of 8,
15360 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c   it is internall
15370 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77  y.** rounded dow
15380 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d  n to the next sm
15390 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  aller multiple o
153a0 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b  f 8.  ^(The look
153b0 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  aside memory.** 
153c0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
153d0 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  r a database con
153e0 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79  nection can only
153f0 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e   be changed when
15400 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74   that.** connect
15410 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65  ion is not curre
15420 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61  ntly using looka
15430 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20  side memory, or 
15440 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a  in other words.*
15450 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72  * when the "curr
15460 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72  ent value" retur
15470 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
15480 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c  e3_db_status](D,
15490 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
154a0 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69  OOKASIDE],...) i
154b0 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61  s zero..** Any a
154c0 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65  ttempt to change
154d0 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   the lookaside m
154e0 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74  emory configurat
154f0 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69  ion when lookasi
15500 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20  de.** memory is 
15510 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68  in use leaves th
15520 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
15530 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65  unchanged and re
15540 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  turns .** [SQLIT
15550 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a  E_BUSY].)^</dd>.
15560 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
15570 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
15580 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _FKEY</dt>.** <d
15590 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
155a0 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
155b0 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  e or disable the
155c0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a   enforcement of.
155d0 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
155e0 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54  constraints].  T
155f0 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
15600 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
15610 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
15620 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
15630 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
15640 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
15650 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
15660 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  t,.** positive t
15670 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f  o enable FK enfo
15680 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74  rcement or negat
15690 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20  ive to leave FK 
156a0 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75  enforcement.** u
156b0 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73  nchanged.  The s
156c0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
156d0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
156e0 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
156f0 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
15700 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
15710 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46  dicate whether F
15720 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73  K enforcement is
15730 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f   off or on.** fo
15740 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
15750 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
15760 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
15770 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
15780 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
15790 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d   the FK enforcem
157a0 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e  ent setting is n
157b0 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
157c0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  . </dd>.**.** <d
157d0 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
157e0 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
157f0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
15800 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
15810 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
15820 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20  disable [CREATE 
15830 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
15840 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68  rs]..** There sh
15850 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
15860 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
15870 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
15880 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
15890 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
158a0 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67   to disable trig
158b0 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76  gers,.** positiv
158c0 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67  e to enable trig
158d0 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65  gers or negative
158e0 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65   to leave the se
158f0 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e  tting unchanged.
15900 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
15910 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
15920 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
15930 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
15940 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
15950 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
15960 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73  whether triggers
15970 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72   are disabled or
15980 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c   enabled.** foll
15990 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
159a0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
159b0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
159c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
159d0 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
159e0 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69  he trigger setti
159f0 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
15a00 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
15a10 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  *.** </dl>.*/.#d
15a20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
15a30 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
15a40 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76        1001  /* v
15a50 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a  oid* int int */.
15a60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
15a70 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
15a80 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a  KEY     1002  /*
15a90 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
15aa0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
15ab0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47  NFIG_ENABLE_TRIG
15ac0 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e  GER  1003  /* in
15ad0 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a  t int* */.../*.*
15ae0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
15af0 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
15b00 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
15b10 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  des.**.** ^The s
15b20 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
15b30 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72  result_codes() r
15b40 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
15b50 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a  r disables the.*
15b60 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
15b70 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
15b80 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68  e of SQLite. ^Th
15b90 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
15ba0 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64  t.** codes are d
15bb0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
15bc0 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61  lt for historica
15bd0 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  l compatibility.
15be0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
15bf0 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
15c00 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20  codes(sqlite3*, 
15c10 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a  int onoff);../*.
15c20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73  ** CAPI3REF: Las
15c30 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a  t Insert Rowid.*
15c40 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79  *.** ^Each entry
15c50 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61   in an SQLite ta
15c60 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75 65  ble has a unique
15c70 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a   64-bit signed.*
15c80 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61  * integer key ca
15c90 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20  lled the [ROWID 
15ca0 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65  | "rowid"]. ^The
15cb0 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73   rowid is always
15cc0 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73   available.** as
15cd0 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63   an undeclared c
15ce0 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49  olumn named ROWI
15cf0 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49  D, OID, or _ROWI
15d00 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  D_ as long as th
15d10 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65  ose.** names are
15d20 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62   not also used b
15d30 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  y explicitly dec
15d40 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e  lared columns. ^
15d50 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20  If.** the table 
15d60 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20  has a column of 
15d70 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52  type [INTEGER PR
15d80 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20  IMARY KEY] then 
15d90 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  that column.** i
15da0 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20  s another alias 
15db0 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a  for the rowid..*
15dc0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
15dd0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ne returns the [
15de0 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f  rowid] of the mo
15df0 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63  st recent.** suc
15e00 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
15e10 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61   into the databa
15e20 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74  se from the [dat
15e30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15e40 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73  ].** in the firs
15e50 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 41 73  t argument.  ^As
15e60 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69   of SQLite versi
15e70 6f 6e 20 33 2e 37 2e 37 2c 20 74 68 69 73 20 72  on 3.7.7, this r
15e80 6f 75 74 69 6e 65 73 0a 2a 2a 20 72 65 63 6f 72  outines.** recor
15e90 64 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65  ds the last inse
15ea0 72 74 20 72 6f 77 69 64 20 6f 66 20 62 6f 74 68  rt rowid of both
15eb0 20 6f 72 64 69 6e 61 72 79 20 74 61 62 6c 65 73   ordinary tables
15ec0 20 61 6e 64 20 5b 76 69 72 74 75 61 6c 20 74 61   and [virtual ta
15ed0 62 6c 65 73 5d 2e 0a 2a 2a 20 5e 49 66 20 6e 6f  bles]..** ^If no
15ee0 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
15ef0 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76  ERT]s.** have ev
15f00 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74  er occurred on t
15f10 68 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e  hat database con
15f20 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73  nection, zero is
15f30 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
15f40 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54   ^(If an [INSERT
15f50 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  ] occurs within 
15f60 61 20 74 72 69 67 67 65 72 20 6f 72 20 77 69 74  a trigger or wit
15f70 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74  hin a [virtual t
15f80 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c  able].** method,
15f90 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
15fa0 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74  ne will return t
15fb0 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
15fc0 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f  e inserted.** ro
15fd0 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  w as long as the
15fe0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
15ff0 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64  ual table method
16000 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20   is running..** 
16010 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69  But once the tri
16020 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20  gger or virtual 
16030 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64  table method end
16040 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  s, the value ret
16050 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69  urned .** by thi
16060 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74  s routine revert
16070 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73  s to what it was
16080 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67   before the trig
16090 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a  ger or virtual.*
160a0 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62  * table method b
160b0 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41  egan.)^.**.** ^A
160c0 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20  n [INSERT] that 
160d0 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63  fails due to a c
160e0 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
160f0 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20  ion is not a.** 
16100 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
16110 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  RT] and does not
16120 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
16130 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
16140 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20  is.** routine.  
16150 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20  ^Thus INSERT OR 
16160 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20  FAIL, INSERT OR 
16170 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f  IGNORE, INSERT O
16180 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61  R ROLLBACK,.** a
16190 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f  nd INSERT OR ABO
161a0 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67  RT make no chang
161b0 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e  es to the return
161c0 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a   value of this.*
161d0 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74  * routine when t
161e0 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66  heir insertion f
161f0 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e  ails.  ^(When IN
16200 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a  SERT OR REPLACE.
16210 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20  ** encounters a 
16220 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
16230 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f  tion, it does no
16240 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20  t fail.  The.** 
16250 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73  INSERT continues
16260 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61   to completion a
16270 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f  fter deleting ro
16280 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a  ws that caused.*
16290 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74  * the constraint
162a0 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45   problem so INSE
162b0 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69  RT OR REPLACE wi
162c0 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65  ll always change
162d0 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76  .** the return v
162e0 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74  alue of this int
162f0 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  erface.)^.**.** 
16300 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65  ^For the purpose
16310 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  s of this routin
16320 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69  e, an [INSERT] i
16330 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a  s considered to.
16340 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c  ** be successful
16350 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73   even if it is s
16360 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c  ubsequently roll
16370 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54  ed back..**.** T
16380 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
16390 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51  accessible to SQ
163a0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61  L statements via
163b0 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e   the.** [last_in
163c0 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c  sert_rowid() SQL
163d0 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
163e0 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
163f0 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20  thread performs 
16400 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f  a new [INSERT] o
16410 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61  n the same.** da
16420 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16430 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c  n while the [sql
16440 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
16450 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e  _rowid()].** fun
16460 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
16470 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65   and thus change
16480 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72  s the last inser
16490 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68  t [rowid],.** th
164a0 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
164b0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
164c0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
164d0 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70  wid()] is.** unp
164e0 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d  redictable and m
164f0 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65  ight not equal e
16500 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72  ither the old or
16510 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74   the new.** last
16520 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e   insert [rowid].
16530 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
16540 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  4 sqlite3_last_i
16550 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69  nsert_rowid(sqli
16560 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
16570 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68  PI3REF: Count Th
16580 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  e Number Of Rows
16590 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20   Modified.**.** 
165a0 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
165b0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
165c0 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f  r of database ro
165d0 77 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61  ws that were cha
165e0 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72  nged.** or inser
165f0 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62  ted or deleted b
16600 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  y the most recen
16610 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51  tly completed SQ
16620 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f  L statement.** o
16630 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  n the [database 
16640 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
16650 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72  ified by the fir
16660 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  st parameter..**
16670 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20   ^(Only changes 
16680 74 68 61 74 20 61 72 65 20 64 69 72 65 63 74 6c  that are directl
16690 79 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  y specified by t
166a0 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50  he [INSERT], [UP
166b0 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45  DATE],.** or [DE
166c0 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 20  LETE] statement 
166d0 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75  are counted.  Au
166e0 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20  xiliary changes 
166f0 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69  caused by.** tri
16700 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 65 69 67  ggers or [foreig
16710 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61  n key actions] a
16720 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29  re not counted.)
16730 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71  ^ Use the.** [sq
16740 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
16750 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20  ges()] function 
16760 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61  to find the tota
16770 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e  l number of chan
16780 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67  ges.** including
16790 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
167a0 62 79 20 74 72 69 67 67 65 72 73 20 61 6e 64 20  by triggers and 
167b0 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
167c0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e  ons..**.** ^Chan
167d0 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68  ges to a view th
167e0 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74 65 64  at are simulated
167f0 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41 44 20   by an [INSTEAD 
16800 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61  OF trigger].** a
16810 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20  re not counted. 
16820 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c 65   Only real table
16830 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75   changes are cou
16840 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20  nted..**.** ^(A 
16850 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73 20  "row change" is 
16860 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73 69  a change to a si
16870 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73 69  ngle row of a si
16880 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61  ngle table.** ca
16890 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45 52  used by an INSER
168a0 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55 50  T, DELETE, or UP
168b0 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e 20  DATE statement. 
168c0 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61 72   Rows that.** ar
168d0 65 20 63 68 61 6e 67 65 64 20 61 73 20 73 69 64  e changed as sid
168e0 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b 52 45  e effects of [RE
168f0 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e  PLACE] constrain
16900 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a  t resolution,.**
16910 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54   rollback, ABORT
16920 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52   processing, [DR
16930 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79  OP TABLE], or by
16940 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65   any other.** me
16950 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20  chanisms do not 
16960 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74 20  count as direct 
16970 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a  row changes.)^.*
16980 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20  *.** A "trigger 
16990 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73 63  context" is a sc
169a0 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e  ope of execution
169b0 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64   that begins and
169c0 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68  .** ends with th
169d0 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 5b 43  e script of a [C
169e0 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
169f0 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f  trigger]. .** Mo
16a00 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
16a10 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74  s are.** evaluat
16a20 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  ed outside of an
16a30 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 69 73  y trigger.  This
16a40 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65 76   is the "top lev
16a50 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 63  el".** trigger c
16a60 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74 72  ontext.  If a tr
16a70 69 67 67 65 72 20 66 69 72 65 73 20 66 72 6f 6d  igger fires from
16a80 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20   the top level, 
16a90 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 72  a.** new trigger
16aa0 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 65   context is ente
16ab0 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 72 61  red for the dura
16ac0 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65  tion of that one
16ad0 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53 75  .** trigger.  Su
16ae0 62 74 72 69 67 67 65 72 73 20 63 72 65 61 74 65  btriggers create
16af0 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f 72   subcontexts for
16b00 20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e 2e   their duration.
16b10 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
16b20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
16b30 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   or [sqlite3_ste
16b40 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79  p()] recursively
16b50 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65   does.** not cre
16b60 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67 65  ate a new trigge
16b70 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
16b80 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
16b90 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
16ba0 65 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77  er of direct row
16bb0 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a   changes in the.
16bc0 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49  ** most recent I
16bd0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
16be0 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
16bf0 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  nt within the sa
16c00 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f  me.** trigger co
16c10 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ntext..**.** ^Th
16c20 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20  us, when called 
16c30 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76  from the top lev
16c40 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  el, this functio
16c50 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  n returns the.**
16c60 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67   number of chang
16c70 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72  es in the most r
16c80 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50  ecent INSERT, UP
16c90 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
16ca0 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63  ** that also occ
16cb0 75 72 72 65 64 20 61 74 20 74 68 65 20 74 6f 70  urred at the top
16cc0 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74 68 69   level.  ^(Withi
16cd0 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20  n the body of a 
16ce0 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20  trigger,.** the 
16cf0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
16d00 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  ) interface can 
16d10 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e  be called to fin
16d20 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  d the number of.
16d30 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ** changes in th
16d40 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
16d50 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54  completed INSERT
16d60 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
16d70 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ETE.** statement
16d80 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79   within the body
16d90 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72 69   of the same tri
16da0 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  gger..** However
16db0 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74  , the number ret
16dc0 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69  urned does not i
16dd0 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a 2a  nclude changes.*
16de0 2a 20 63 61 75 73 65 64 20 62 79 20 73 75 62 74  * caused by subt
16df0 72 69 67 67 65 72 73 20 73 69 6e 63 65 20 74 68  riggers since th
16e00 6f 73 65 20 68 61 76 65 20 74 68 65 69 72 20 6f  ose have their o
16e10 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a  wn context.)^.**
16e20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
16e30 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
16e40 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72  changes()] inter
16e50 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f  face, the.** [co
16e60 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67  unt_changes prag
16e70 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68  ma], and the [ch
16e80 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
16e90 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
16ea0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
16eb0 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
16ec0 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
16ed0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
16ee0 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
16ef0 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  3_changes()] is 
16f00 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
16f10 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
16f20 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ** is unpredicta
16f30 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
16f40 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  ingful..*/.int s
16f50 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73  qlite3_changes(s
16f60 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
16f70 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c   CAPI3REF: Total
16f80 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
16f90 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e  Modified.**.** ^
16fa0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
16fb0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
16fc0 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20   of row changes 
16fd0 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52  caused by [INSER
16fe0 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20  T],.** [UPDATE] 
16ff0 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74  or [DELETE] stat
17000 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65  ements since the
17010 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
17020 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65  ction] was opene
17030 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e  d..** ^(The coun
17040 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  t returned by sq
17050 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
17060 67 65 73 28 29 20 69 6e 63 6c 75 64 65 73 20 61  ges() includes a
17070 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72  ll changes.** fr
17080 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45 20 54  om all [CREATE T
17090 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
170a0 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 63  ] contexts and c
170b0 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79 0a 2a  hanges made by.*
170c0 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  * [foreign key a
170d0 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72  ctions]. However
170e0 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64  ,.** the count d
170f0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
17100 63 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20  changes used to 
17110 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41  implement [REPLA
17120 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c  CE] constraints,
17130 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73  .** do rollbacks
17140 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73   or ABORT proces
17150 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54  sing, or [DROP T
17160 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67  ABLE] processing
17170 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20  .  The.** count 
17180 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
17190 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74   rows of views t
171a0 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53  hat fire an [INS
171b0 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d  TEAD OF trigger]
171c0 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74  ,.** though if t
171d0 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72  he INSTEAD OF tr
171e0 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e  igger makes chan
171f0 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20  ges of its own, 
17200 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a  those changes .*
17210 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e  * are counted.)^
17220 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
17230 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
17240 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73   function counts
17250 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 73 20   the changes as 
17260 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73  soon as.** the s
17270 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61  tatement that ma
17280 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70  kes them is comp
17290 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 20  leted (when the 
172a0 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  statement handle
172b0 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 74 6f  .** is passed to
172c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
172d0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
172e0 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a  inalize()])..**.
172f0 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
17300 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
17310 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74  ()] interface, t
17320 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61  he.** [count_cha
17330 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e  nges pragma], an
17340 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61  d the [total_cha
17350 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
17360 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
17370 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
17380 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
17390 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
173a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
173b0 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  * while [sqlite3
173c0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
173d0 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
173e0 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72  n the value.** r
173f0 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65  eturned is unpre
17400 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
17410 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
17420 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61  int sqlite3_tota
17430 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  l_changes(sqlite
17440 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
17450 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20  3REF: Interrupt 
17460 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51  A Long-Running Q
17470 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  uery.**.** ^This
17480 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
17490 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74   any pending dat
174a0 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20  abase operation 
174b0 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20  to abort and.** 
174c0 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61  return at its ea
174d0 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69  rliest opportuni
174e0 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65  ty. This routine
174f0 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a   is typically.**
17500 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f   called in respo
17510 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63  nse to a user ac
17520 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65  tion such as pre
17530 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a  ssing "Cancel".*
17540 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72  * or Ctrl-C wher
17550 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73  e the user wants
17560 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70   a long query op
17570 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a  eration to halt.
17580 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ** immediately..
17590 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66  **.** ^It is saf
175a0 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
175b0 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68  outine from a th
175c0 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66  read different f
175d0 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61  rom the.** threa
175e0 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e  d that is curren
175f0 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20  tly running the 
17600 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
17610 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69  on.  But it.** i
17620 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61  s not safe to ca
17630 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
17640 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
17650 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
17660 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f  t.** is closed o
17670 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65  r might close be
17680 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  fore sqlite3_int
17690 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73  errupt() returns
176a0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53  ..**.** ^If an S
176b0 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
176c0 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69  very nearly fini
176d0 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65  shed at the time
176e0 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   when.** sqlite3
176f0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20  _interrupt() is 
17700 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20  called, then it 
17710 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61  might not have a
17720 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a  n opportunity.**
17730 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74   to be interrupt
17740 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e  ed and might con
17750 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74  tinue to complet
17760 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53  ion..**.** ^An S
17770 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  QL operation tha
17780 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64  t is interrupted
17790 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
177a0 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e  LITE_INTERRUPT].
177b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65  .** ^If the inte
177c0 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72  rrupted SQL oper
177d0 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45  ation is an INSE
177e0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
177f0 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73  ELETE.** that is
17800 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69   inside an expli
17810 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
17820 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65   then the entire
17830 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20   transaction.** 
17840 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62  will be rolled b
17850 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
17860 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
17870 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
17880 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66  D) call is in ef
17890 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63  fect until all c
178a0 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
178b0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
178c0 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ts on [database 
178d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f  connection] D co
178e0 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65  mplete.  ^Any ne
178f0 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
17900 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
17910 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
17920 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
17930 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f  () call and befo
17940 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69  re the .** runni
17950 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65  ng statements re
17960 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69  aches zero are i
17970 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66  nterrupted as if
17980 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a   they had been.*
17990 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20  * running prior 
179a0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  to the sqlite3_i
179b0 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e  nterrupt() call.
179c0 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65    ^New SQL state
179d0 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
179e0 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
179f0 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  the running stat
17a00 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63  ement count reac
17a10 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20  hes zero are.** 
17a20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20  not effected by 
17a30 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
17a40 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63  rrupt()..** ^A c
17a50 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
17a60 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74  nterrupt(D) that
17a70 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65   occurs when the
17a80 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e  re are no runnin
17a90 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  g.** SQL stateme
17aa0 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61  nts is a no-op a
17ab0 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74  nd has no effect
17ac0 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   on SQL statemen
17ad0 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
17ae0 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
17af0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
17b00 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e  pt() call return
17b10 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  s..**.** If the 
17b20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17b30 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65  ion closes while
17b40 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
17b50 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e  upt()].** is run
17b60 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68  ning then bad th
17b70 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  ings will likely
17b80 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64   happen..*/.void
17b90 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
17ba0 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  pt(sqlite3*);../
17bb0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
17bc0 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53  etermine If An S
17bd0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20  QL Statement Is 
17be0 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54  Complete.**.** T
17bf0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
17c00 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20  e useful during 
17c10 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70  command-line inp
17c20 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ut to determine 
17c30 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  if the.** curren
17c40 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74  tly entered text
17c50 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61   seems to form a
17c60 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
17c70 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66  atement or.** if
17c80 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75   additional inpu
17c90 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f  t is needed befo
17ca0 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74  re sending the t
17cb0 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69  ext into.** SQLi
17cc0 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20  te for parsing. 
17cd0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
17ce0 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65   return 1 if the
17cf0 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a   input string.**
17d00 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61   appears to be a
17d10 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
17d20 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61  atement.  ^A sta
17d30 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64  tement is judged
17d40 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65   to be.** comple
17d50 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69  te if it ends wi
17d60 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74  th a semicolon t
17d70 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20  oken and is not 
17d80 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a  a prefix of a.**
17d90 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45   well-formed CRE
17da0 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74  ATE TRIGGER stat
17db0 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c  ement.  ^Semicol
17dc0 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62  ons that are emb
17dd0 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  edded within.** 
17de0 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20  string literals 
17df0 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69  or quoted identi
17e00 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f  fier names or co
17e10 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a  mments are not.*
17e20 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f  * independent to
17e30 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70  kens (they are p
17e40 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e  art of the token
17e50 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61   in which they a
17e60 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20  re.** embedded) 
17e70 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20  and thus do not 
17e80 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65  count as a state
17e90 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e  ment terminator.
17ea0 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a    ^Whitespace.**
17eb0 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68   and comments th
17ec0 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69  at follow the fi
17ed0 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72  nal semicolon ar
17ee0 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  e ignored..**.**
17ef0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
17f00 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65   return 0 if the
17f10 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e   statement is in
17f20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61  complete.  ^If a
17f30 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
17f40 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65  ation fails, the
17f50 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69  n SQLITE_NOMEM i
17f60 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
17f70 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
17f80 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74  s do not parse t
17f90 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
17fa0 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e  s thus.** will n
17fb0 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63  ot detect syntac
17fc0 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63  tically incorrec
17fd0 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  t SQL..**.** ^(I
17fe0 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74  f SQLite has not
17ff0 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65   been initialize
18000 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
18010 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70  _initialize()] p
18020 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f  rior .** to invo
18030 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d  king sqlite3_com
18040 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73  plete16() then s
18050 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
18060 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
18070 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
18080 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  by sqlite3_compl
18090 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61  ete16().  If tha
180a0 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  t initialization
180b0 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20   fails,.** then 
180c0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
180d0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
180e0 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20  mplete16() will 
180f0 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72  be non-zero.** r
18100 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
18110 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
18120 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d  input SQL is com
18130 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  plete.)^.**.** T
18140 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
18150 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d  ite3_complete()]
18160 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
18170 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
18180 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  F-8 string..**.*
18190 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
181a0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
181b0 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  16()] must be a 
181c0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
181d0 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
181e0 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
181f0 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  order..*/.int sq
18200 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63  lite3_complete(c
18210 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b  onst char *sql);
18220 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d  .int sqlite3_com
18230 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f  plete16(const vo
18240 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  id *sql);../*.**
18250 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73   CAPI3REF: Regis
18260 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54  ter A Callback T
18270 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f  o Handle SQLITE_
18280 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a  BUSY Errors.**.*
18290 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
182a0 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  sets a callback 
182b0 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69  function that mi
182c0 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
182d0 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74  henever.** an at
182e0 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f  tempt is made to
182f0 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65   open a database
18300 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74   table that anot
18310 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72  her thread.** or
18320 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63   process has loc
18330 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ked..**.** ^If t
18340 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
18350 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b   is NULL, then [
18360 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
18370 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
18380 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74  OCKED].** is ret
18390 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
183a0 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72  y upon encounter
183b0 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e  ing the lock.  ^
183c0 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
183d0 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  back.** is not N
183e0 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61  ULL, then the ca
183f0 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20  llback might be 
18400 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f  invoked with two
18410 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
18420 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
18430 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73  ument to the bus
18440 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63  y handler is a c
18450 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
18460 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a   pointer which.*
18470 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61  * is the third a
18480 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
18490 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
184a0 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ).  ^The second 
184b0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
184c0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
184d0 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
184e0 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
184f0 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61  that the busy ha
18500 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65  ndler has.** bee
18510 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68  n invoked for th
18520 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  is locking event
18530 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75  .  ^If the.** bu
18540 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  sy callback retu
18550 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61  rns 0, then no a
18560 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70  dditional attemp
18570 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a  ts are made to.*
18580 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  * access the dat
18590 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54  abase and [SQLIT
185a0 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
185b0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
185c0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
185d0 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61  * ^If the callba
185e0 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
185f0 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65  ero, then anothe
18600 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20  r attempt.** is 
18610 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65  made to open the
18620 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65   database for re
18630 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79  ading and the cy
18640 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a  cle repeats..**.
18650 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20  ** The presence 
18660 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65  of a busy handle
18670 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61  r does not guara
18680 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c  ntee that it wil
18690 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  l be invoked.** 
186a0 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f  when there is lo
186b0 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e  ck contention. ^
186c0 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d  If SQLite determ
186d0 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69  ines that invoki
186e0 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68  ng the busy.** h
186f0 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73  andler could res
18700 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63  ult in a deadloc
18710 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68  k, it will go ah
18720 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  ead and return [
18730 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
18740 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
18750 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61  _BLOCKED] instea
18760 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68  d of invoking th
18770 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
18780 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63  ** Consider a sc
18790 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65  enario where one
187a0 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
187b0 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20  ing a read lock 
187c0 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72  that.** it is tr
187d0 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20  ying to promote 
187e0 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  to a reserved lo
187f0 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f  ck and.** a seco
18800 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  nd process is ho
18810 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64  lding a reserved
18820 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73   lock that it is
18830 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72   trying.** to pr
18840 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c  omote to an excl
18850 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65  usive lock.  The
18860 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63   first process c
18870 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a  annot proceed.**
18880 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
18890 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65  locked by the se
188a0 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63  cond and the sec
188b0 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  ond process cann
188c0 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65  ot.** proceed be
188d0 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
188e0 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ked by the first
188f0 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65  .  If both proce
18900 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74  sses.** invoke t
18910 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  he busy handlers
18920 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d  , neither will m
18930 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73  ake any progress
18940 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a  .  Therefore,.**
18950 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20   SQLite returns 
18960 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f  [SQLITE_BUSY] fo
18970 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  r the first proc
18980 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74  ess, hoping that
18990 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e   this.** will in
189a0 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70  duce the first p
189b0 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73  rocess to releas
189c0 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20  e its read lock 
189d0 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65  and allow.** the
189e0 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
189f0 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a  to proceed..**.*
18a00 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62  * ^The default b
18a10 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
18a20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
18a30 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65   [SQLITE_BUSY] e
18a40 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65  rror is converte
18a50 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45  d to [SQLITE_IOE
18a60 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77  RR_BLOCKED].** w
18a70 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e  hen SQLite is in
18a80 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61   the middle of a
18a90 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69   large transacti
18aa0 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65  on where all the
18ab0 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c  .** changes will
18ac0 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68   not fit into th
18ad0 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68  e in-memory cach
18ae0 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a  e.  SQLite will.
18af0 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20  ** already hold 
18b00 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20  a RESERVED lock 
18b10 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
18b20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65  file, but it nee
18b30 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ds.** to promote
18b40 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58   this lock to EX
18b50 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 20  CLUSIVE so that 
18b60 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63  it can spill cac
18b70 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f  he.** pages into
18b80 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
18b90 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20  le without harm 
18ba0 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a  to concurrent.**
18bb0 20 72 65 61 64 65 72 73 2e 20 20 5e 49 66 20 69   readers.  ^If i
18bc0 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70  t is unable to p
18bd0 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c  romote the lock,
18be0 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d   then the in-mem
18bf0 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c  ory.** cache wil
18c00 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20  l be left in an 
18c10 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61  inconsistent sta
18c20 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72  te and so the er
18c30 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70  ror.** code is p
18c40 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65  romoted from the
18c50 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69   relatively beni
18c60 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  gn [SQLITE_BUSY]
18c70 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20   to.** the more 
18c80 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49  severe [SQLITE_I
18c90 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20  OERR_BLOCKED].  
18ca0 5e 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65  ^This error code
18cb0 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f   promotion.** fo
18cc0 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69  rces an automati
18cd0 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68  c rollback of th
18ce0 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20  e changes.  See 
18cf0 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
18d00 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d  /cvstrac/wiki?p=
18d10 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77  CorruptionFollow
18d20 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a  ingBusyError">.*
18d30 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c  * CorruptionFoll
18d40 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f  owingBusyError</
18d50 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72  a> wiki page for
18d60 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66   a discussion of
18d70 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20   why.** this is 
18d80 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a  important..**.**
18d90 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
18da0 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
18db0 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e  sy handler defin
18dc0 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b  ed for each.** [
18dd0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18de0 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61  ion].  Setting a
18df0 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65   new busy handle
18e00 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20  r clears any.** 
18e10 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68  previously set h
18e20 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65  andler.)^  ^Note
18e30 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73   that calling [s
18e40 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
18e50 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61  out()].** will a
18e60 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72  lso set or clear
18e70 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
18e80 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73  r..**.** The bus
18e90 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  y callback shoul
18ea0 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61  d not take any a
18eb0 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64  ctions which mod
18ec0 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ify the.** datab
18ed0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
18ee0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
18ef0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41  busy handler.  A
18f00 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a  ny such actions.
18f10 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  ** result in und
18f20 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
18f30 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68  .** .** A busy h
18f40 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20  andler must not 
18f50 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
18f60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
18f70 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74   or [prepared st
18f80 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e  atement] that in
18f90 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
18fa0 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73  andler..*/.int s
18fb0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
18fc0 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
18fd0 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c  t(*)(void*,int),
18fe0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
18ff0 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20  CAPI3REF: Set A 
19000 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a  Busy Timeout.**.
19010 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
19020 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33   sets a [sqlite3
19030 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20  _busy_handler | 
19040 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68  busy handler] th
19050 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72  at sleeps.** for
19060 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f   a specified amo
19070 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e  unt of time when
19080 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b   a table is lock
19090 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65  ed.  ^The handle
190a0 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20  r.** will sleep 
190b0 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75  multiple times u
190c0 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d  ntil at least "m
190d0 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
190e0 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68  of sleeping.** h
190f0 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e  ave accumulated.
19100 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73    ^After at leas
19110 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
19120 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c  nds of sleeping,
19130 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20  .** the handler 
19140 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20  returns 0 which 
19150 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f  causes [sqlite3_
19160 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72  step()] to retur
19170 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53  n.** [SQLITE_BUS
19180 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
19190 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a  ERR_BLOCKED]..**
191a0 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69  .** ^Calling thi
191b0 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
191c0 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20  n argument less 
191d0 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
191e0 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f   zero.** turns o
191f0 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64  ff all busy hand
19200 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  lers..**.** ^(Th
19210 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
19220 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
19230 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74  ndler for a part
19240 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
19250 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
19260 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f  any any given mo
19270 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65  ment.  If anothe
19280 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a  r busy handler.*
19290 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28  * was defined  (
192a0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  using [sqlite3_b
192b0 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20  usy_handler()]) 
192c0 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
192d0 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
192e0 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73  , that other bus
192f0 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65  y handler is cle
19300 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73  ared.)^.*/.int s
19310 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
19320 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  out(sqlite3*, in
19330 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t ms);../*.** CA
19340 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65  PI3REF: Convenie
19350 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72  nce Routines For
19360 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73   Running Queries
19370 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  .**.** This is a
19380 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
19390 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72  e that is preser
193a0 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ved for backward
193b0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
193c0 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20  .** Use of this 
193d0 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
193e0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a   recommended..**
193f0 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20  .** Definition: 
19400 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c  A <b>result tabl
19410 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20  e</b> is memory 
19420 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63  data structure c
19430 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a  reated by the.**
19440 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
19450 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ble()] interface
19460 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  .  A result tabl
19470 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a  e records the.**
19480 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20   complete query 
19490 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65  results from one
194a0 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73   or more queries
194b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ..**.** The tabl
194c0 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68  e conceptually h
194d0 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72  as a number of r
194e0 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e  ows and columns.
194f0 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e    But.** these n
19500 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70  umbers are not p
19510 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c  art of the resul
19520 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20  t table itself. 
19530 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72   These.** number
19540 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73  s are obtained s
19550 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20  eparately.  Let 
19560 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  N be the number 
19570 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d  of rows.** and M
19580 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
19590 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a  f columns..**.**
195a0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
195b0 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
195c0 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d  ointers to zero-
195d0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
195e0 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65   strings..** The
195f0 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65  re are (N+1)*M e
19600 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61  lements in the a
19610 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74  rray.  The first
19620 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e   M pointers poin
19630 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72  t.** to zero-ter
19640 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
19650 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68  that  contain th
19660 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63  e names of the c
19670 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72  olumns..** The r
19680 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73  emaining entries
19690 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75   all point to qu
196a0 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55  ery results.  NU
196b0 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74  LL values result
196c0 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e  .** in NULL poin
196d0 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72  ters.  All other
196e0 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74   values are in t
196f0 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d  heir UTF-8 zero-
19700 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
19710 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74  ring representat
19720 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20  ion as returned 
19730 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
19740 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a  mn_text()]..**.*
19750 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
19760 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f   might consist o
19770 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65  f one or more me
19780 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
19790 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  ..** It is not s
197a0 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65  afe to pass a re
197b0 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63  sult table direc
197c0 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  tly to [sqlite3_
197d0 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65  free()]..** A re
197e0 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c  sult table shoul
197f0 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  d be deallocated
19800 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
19810 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a  free_table()]..*
19820 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61  *.** ^(As an exa
19830 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75  mple of the resu
19840 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c  lt table format,
19850 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79   suppose a query
19860 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73   result.** is as
19870 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
19880 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
19890 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65  >.**        Name
198a0 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a          | Age.**
198b0 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d          --------
198c0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
198d0 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20  **        Alice 
198e0 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20        | 43.**   
198f0 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20       Bob        
19900 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20   | 28.**        
19910 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31  Cindy       | 21
19920 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
19930 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
19940 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75  ere are two colu
19950 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68  mn (M==2) and th
19960 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e  ree rows (N==3).
19970 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65    Thus the.** re
19980 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38  sult table has 8
19990 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f   entries.  Suppo
199a0 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  se the result ta
199b0 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a  ble is stored.**
199c0 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d   in an array nam
199d0 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68  es azResult.  Th
199e0 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64  en azResult hold
199f0 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a  s this content:.
19a00 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
19a10 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
19a20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30    azResult&#91;0
19a30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20  ] = "Name";.**  
19a40 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
19a50 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a  91;1] = "Age";.*
19a60 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
19a70 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63  t&#91;2] = "Alic
19a80 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
19a90 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20  Result&#91;3] = 
19aa0 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "43";.**        
19ab0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20  azResult&#91;4] 
19ac0 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20  = "Bob";.**     
19ad0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
19ae0 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20  5] = "28";.**   
19af0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
19b00 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a  1;6] = "Cindy";.
19b10 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
19b20 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22  lt&#91;7] = "21"
19b30 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
19b40 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
19b50 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
19b60 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69  t_table() functi
19b70 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65  on evaluates one
19b80 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69   or more.** semi
19b90 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20  colon-separated 
19ba0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
19bb0 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  n the zero-termi
19bc0 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73  nated UTF-8.** s
19bd0 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64  tring of its 2nd
19be0 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
19bf0 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20  eturns a result 
19c00 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20  table to the.** 
19c10 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e  pointer given in
19c20 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74   its 3rd paramet
19c30 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  er..**.** After 
19c40 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
19c50 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
19c60 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  h the result fro
19c70 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  m sqlite3_get_ta
19c80 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73  ble(),.** it mus
19c90 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c  t pass the resul
19ca0 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20  t table pointer 
19cb0 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  to sqlite3_free_
19cc0 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72  table() in order
19cd0 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74   to.** release t
19ce0 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77  he memory that w
19cf0 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65  as malloced.  Be
19d00 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79  cause of the way
19d10 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
19d20 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65  _malloc()] happe
19d30 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65  ns within sqlite
19d40 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74  3_get_table(), t
19d50 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75  he calling.** fu
19d60 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  nction must not 
19d70 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c  try to call [sql
19d80 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72  ite3_free()] dir
19d90 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20  ectly.  Only.** 
19da0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
19db0 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74  ble()] is able t
19dc0 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  o release the me
19dd0 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e  mory properly an
19de0 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  d safely..**.** 
19df0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
19e00 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  table() interfac
19e10 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
19e20 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72   as a wrapper ar
19e30 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
19e40 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73  _exec()].  The s
19e50 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
19e60 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
19e70 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a  not have access.
19e80 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e  ** to any intern
19e90 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72  al data structur
19ea0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49  es of SQLite.  I
19eb0 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20  t uses only the 
19ec0 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66  public.** interf
19ed0 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65  ace defined here
19ee0 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65  .  As a conseque
19ef0 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74  nce, errors that
19f00 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a   occur in the.**
19f10 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f   wrapper layer o
19f20 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e  utside of the in
19f30 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f  ternal [sqlite3_
19f40 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65  exec()] call are
19f50 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65   not.** reflecte
19f60 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  d in subsequent 
19f70 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
19f80 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a  3_errcode()] or.
19f90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
19fa0 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  sg()]..*/.int sq
19fb0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
19fc0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
19fd0 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f           /* An o
19fe0 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  pen database */.
19ff0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
1a000 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74  ql,     /* SQL t
1a010 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
1a020 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52  /.  char ***pazR
1a030 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73  esult,    /* Res
1a040 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72  ults of the quer
1a050 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f  y */.  int *pnRo
1a060 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  w,           /* 
1a070 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
1a080 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65   rows written he
1a090 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43  re */.  int *pnC
1a0a0 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a  olumn,        /*
1a0b0 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
1a0c0 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65  t columns writte
1a0d0 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72  n here */.  char
1a0e0 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20   **pzErrmsg     
1a0f0 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
1a100 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
1a110 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
1a120 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a  ree_table(char *
1a130 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a  *result);../*.**
1a140 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61   CAPI3REF: Forma
1a150 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e  tted String Prin
1a160 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ting Functions.*
1a170 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1a180 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69  nes are work-ali
1a190 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e  kes of the "prin
1a1a0 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20  tf()" family of 
1a1b0 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f  functions.** fro
1a1c0 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
1a1d0 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20   library..**.** 
1a1e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72  ^The sqlite3_mpr
1a1f0 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
1a200 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f  e3_vmprintf() ro
1a210 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65  utines write the
1a220 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ir.** results in
1a230 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
1a240 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
1a250 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54  _malloc()]..** T
1a260 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
1a270 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
1a280 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
1a290 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
1a2a0 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
1a2b0 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74  ()].  ^Both rout
1a2c0 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a  ines return a.**
1a2d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
1a2e0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1a2f0 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ()] is unable to
1a300 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68   allocate enough
1a310 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** memory to ho
1a320 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  ld the resulting
1a330 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e   string..**.** ^
1a340 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70  (The sqlite3_snp
1a350 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
1a360 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73  is similar to "s
1a370 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a  nprintf()" from.
1a380 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  ** the standard 
1a390 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  C library.  The 
1a3a0 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65  result is writte
1a3b0 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75  n into the.** bu
1a3c0 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73  ffer supplied as
1a3d0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1a3e0 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65  meter whose size
1a3f0 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20   is given by.** 
1a400 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
1a410 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74  ter. Note that t
1a420 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a  he order of the.
1a430 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72  ** first two par
1a440 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72  ameters is rever
1a450 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74  sed from snprint
1a460 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20  f().)^  This is 
1a470 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c  an.** historical
1a480 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63   accident that c
1a490 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77  annot be fixed w
1a4a0 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a  ithout breaking.
1a4b0 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
1a4c0 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e  patibility.  ^(N
1a4d0 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71  ote also that sq
1a4e0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1a4f0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f  .** returns a po
1a500 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66  inter to its buf
1a510 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74  fer instead of t
1a520 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
1a530 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61  characters actua
1a540 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  lly written into
1a550 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20   the buffer.)^  
1a560 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a  We admit that.**
1a570 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1a580 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65  haracters writte
1a590 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72  n would be a mor
1a5a0 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a  e useful return.
1a5b0 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20  ** value but we 
1a5c0 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  cannot change th
1a5d0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
1a5e0 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
1a5f0 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69  intf().** now wi
1a600 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63  thout breaking c
1a610 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
1a620 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20  .** ^As long as 
1a630 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20  the buffer size 
1a640 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  is greater than 
1a650 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e  zero, sqlite3_sn
1a660 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72  printf().** guar
1a670 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
1a680 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73  buffer is always
1a690 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1a6a0 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a  .  ^The first.**
1a6b0 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69   parameter "n" i
1a6c0 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65  s the total size
1a6d0 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20   of the buffer, 
1a6e0 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20  including space 
1a6f0 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20  for.** the zero 
1a700 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20  terminator.  So 
1a710 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69  the longest stri
1a720 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63  ng that can be c
1a730 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69  ompletely.** wri
1a740 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31  tten will be n-1
1a750 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
1a760 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1a770 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  vsnprintf() rout
1a780 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73  ine is a varargs
1a790 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69   version of sqli
1a7a0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a  te3_snprintf()..
1a7b0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1a7c0 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  ines all impleme
1a7d0 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  nt some addition
1a7e0 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a  al formatting.**
1a7f0 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72   options that ar
1a800 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e  e useful for con
1a810 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74  structing SQL st
1a820 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c  atements..** All
1a830 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72   of the usual pr
1a840 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e  intf() formattin
1a850 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e  g options apply.
1a860 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74    In addition, t
1a870 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22  here.** is are "
1a880 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22  %q", "%Q", and "
1a890 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a  %z" options..**.
1a8a0 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69  ** ^(The %q opti
1a8b0 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73  on works like %s
1a8c0 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73   in that it subs
1a8d0 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65  titutes a nul-te
1a8e0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
1a8f0 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75  ng from the argu
1a900 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20  ment list.  But 
1a910 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20  %q also doubles 
1a920 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61  every '\'' chara
1a930 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64  cter..** %q is d
1a940 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20  esigned for use 
1a950 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20  inside a string 
1a960 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64  literal.)^  By d
1a970 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27  oubling each '\'
1a980 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69  '.** character i
1a990 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63  t escapes that c
1a9a0 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c  haracter and all
1a9b0 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73  ows it to be ins
1a9c0 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  erted into.** th
1a9d0 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  e string..**.** 
1a9e0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73  For example, ass
1a9f0 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76  ume the string v
1aa00 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f  ariable zText co
1aa10 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66  ntains text as f
1aa20 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1aa30 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1aa40 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20  **  char *zText 
1aa50 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20  = "It's a happy 
1aa60 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  day!";.** </pre>
1aa70 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1aa80 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20  .** One can use 
1aa90 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20  this text in an 
1aaa0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
1aab0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1aac0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1aad0 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
1aae0 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
1aaf0 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
1ab00 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71  table VALUES('%q
1ab10 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  ')", zText);.** 
1ab20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
1ab30 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
1ab40 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
1ab50 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
1ab60 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1ab70 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
1ab80 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72  he %q format str
1ab90 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
1aba0 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20   '\'' character 
1abb0 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65  in zText.** is e
1abc0 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53  scaped and the S
1abd0 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20  QL generated is 
1abe0 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1abf0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1ac00 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
1ac10 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
1ac20 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79  S('It''s a happy
1ac30 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65   day!').** </pre
1ac40 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1ac50 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72  *.** This is cor
1ac60 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73  rect.  Had we us
1ac70 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66  ed %s instead of
1ac80 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74   %q, the generat
1ac90 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20  ed SQL.** would 
1aca0 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65  have looked like
1acb0 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c   this:.**.** <bl
1acc0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1acd0 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
1ace0 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
1acf0 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
1ad00 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1ad10 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1ad20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d  This second exam
1ad30 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79  ple is an SQL sy
1ad40 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20  ntax error.  As 
1ad50 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79  a general rule y
1ad60 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77  ou should.** alw
1ad70 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65  ays use %q inste
1ad80 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e  ad of %s when in
1ad90 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74  serting text int
1ada0 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  o a string liter
1adb0 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  al..**.** ^(The 
1adc0 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %Q option works 
1add0 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69  like %q except i
1ade0 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67  t also adds sing
1adf0 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64  le quotes around
1ae00 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20  .** the outside 
1ae10 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72  of the total str
1ae20 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ing.  Additional
1ae30 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d  ly, if the param
1ae40 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61  eter in the.** a
1ae50 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20  rgument list is 
1ae60 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
1ae70 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74  %Q substitutes t
1ae80 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28  he text "NULL" (
1ae90 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c  without.** singl
1aea0 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f  e quotes).)^  So
1aeb0 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f  , for example, o
1aec0 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a  ne could say:.**
1aed0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1aee0 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
1aef0 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
1af00 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
1af10 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
1af20 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  (%Q)", zText);.*
1af30 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
1af40 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
1af50 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
1af60 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
1af70 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1af80 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  e>.**.** The cod
1af90 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e  e above will ren
1afa0 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51  der a correct SQ
1afb0 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  L statement in t
1afc0 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61  he zSQL.** varia
1afd0 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20  ble even if the 
1afe0 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69  zText variable i
1aff0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1b000 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25  ..**.** ^(The "%
1b010 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  z" formatting op
1b020 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1b030 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68  "%s" but with th
1b040 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68  e.** addition th
1b050 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72  at after the str
1b060 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61  ing has been rea
1b070 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74  d and copied int
1b080 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c  o.** the result,
1b090 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1b0a0 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74  ] is called on t
1b0b0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e  he input string.
1b0c0 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69  )^.*/.char *sqli
1b0d0 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73  te3_mprintf(cons
1b0e0 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68  t char*,...);.ch
1b0f0 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72  ar *sqlite3_vmpr
1b100 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
1b110 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72  , va_list);.char
1b120 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   *sqlite3_snprin
1b130 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e  tf(int,char*,con
1b140 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a  st char*, ...);.
1b150 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73  char *sqlite3_vs
1b160 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1b170 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  *,const char*, v
1b180 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  a_list);../*.** 
1b190 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
1b1a0 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73   Allocation Subs
1b1b0 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ystem.**.** The 
1b1c0 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
1b1d0 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75   these three rou
1b1e0 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66  tines for all of
1b1f0 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65   its own.** inte
1b200 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rnal memory allo
1b210 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43  cation needs. "C
1b220 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76  ore" in the prev
1b230 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a  ious sentence.**
1b240 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
1b250 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  e operating-syst
1b260 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20  em specific VFS 
1b270 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
1b280 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20   The.** Windows 
1b290 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20  VFS uses native 
1b2a0 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
1b2b0 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65  e() for some ope
1b2c0 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  rations..**.** ^
1b2d0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  The sqlite3_mall
1b2e0 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  oc() routine ret
1b2f0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1b300 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20  o a block.** of 
1b310 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20  memory at least 
1b320 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74  N bytes in lengt
1b330 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  h, where N is th
1b340 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
1b350 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
1b360 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  oc() is unable t
1b370 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69  o obtain suffici
1b380 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f  ent free.** memo
1b390 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61  ry, it returns a
1b3a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
1b3b0 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65  ^If the paramete
1b3c0 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  r N to.** sqlite
1b3d0 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  3_malloc() is ze
1b3e0 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  ro or negative t
1b3f0 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  hen sqlite3_mall
1b400 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  oc() returns.** 
1b410 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1b420 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  **.** ^Calling s
1b430 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69  qlite3_free() wi
1b440 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65  th a pointer pre
1b450 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
1b460 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  .** by sqlite3_m
1b470 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1b480 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c  e3_realloc() rel
1b490 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72  eases that memor
1b4a0 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20  y so.** that it 
1b4b0 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e  might be reused.
1b4c0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66    ^The sqlite3_f
1b4d0 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ree() routine is
1b4e0 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69  .** a no-op if i
1b4f0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
1b500 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50  NULL pointer.  P
1b510 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f  assing a NULL po
1b520 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69  inter.** to sqli
1b530 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61  te3_free() is ha
1b540 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62  rmless.  After b
1b550 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f  eing freed, memo
1b560 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69  ry.** should nei
1b570 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72  ther be read nor
1b580 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20   written.  Even 
1b590 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73  reading previous
1b5a0 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f  ly freed.** memo
1b5b0 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ry might result 
1b5c0 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  in a segmentatio
1b5d0 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72  n fault or other
1b5e0 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a   severe error..*
1b5f0 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74  * Memory corrupt
1b600 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74  ion, a segmentat
1b610 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74  ion fault, or ot
1b620 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
1b630 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74  .** might result
1b640 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65   if sqlite3_free
1b650 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  () is called wit
1b660 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  h a non-NULL poi
1b670 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73  nter that.** was
1b680 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72   not obtained fr
1b690 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
1b6a0 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
1b6b0 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20  ealloc()..**.** 
1b6c0 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  ^(The sqlite3_re
1b6d0 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63  alloc() interfac
1b6e0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  e attempts to re
1b6f0 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20  size a.** prior 
1b700 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1b710 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74  n to be at least
1b720 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20   N bytes, where 
1b730 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f  N is the.** seco
1b740 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
1b750 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
1b760 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a  tion to be resiz
1b770 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  ed is the first.
1b780 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29 5e 20  ** parameter.)^ 
1b790 5e 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70  ^ If the first p
1b7a0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1b7b0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
1b7c0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1b7d0 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61  er then its beha
1b7e0 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61  vior is identica
1b7f0 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  l to calling.** 
1b800 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
1b810 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  ) where N is the
1b820 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1b830 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
1b840 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74  lloc()..** ^If t
1b850 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1b860 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1b870 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  ealloc() is zero
1b880 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20   or.** negative 
1b890 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
1b8a0 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65  r is exactly the
1b8b0 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67   same as calling
1b8c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65  .** sqlite3_free
1b8d0 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74  (P) where P is t
1b8e0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1b8f0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
1b900 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c  alloc()..** ^sql
1b910 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
1b920 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1b930 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   to a memory all
1b940 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74  ocation.** of at
1b950 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
1b960 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69  n size or NULL i
1b970 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  f sufficient mem
1b980 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62  ory is unavailab
1b990 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20  le..** ^If M is 
1b9a0 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
1b9b0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1b9c0 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20  , then min(N,M) 
1b9d0 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20  bytes.** of the 
1b9e0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1b9f0 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f   are copied into
1ba00 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
1ba10 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65  f buffer returne
1ba20 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
1ba30 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68  realloc() and th
1ba40 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1ba50 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20  on is freed..** 
1ba60 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  ^If sqlite3_real
1ba70 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55  loc() returns NU
1ba80 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69  LL, then the pri
1ba90 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  or allocation.**
1baa0 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a   is not freed..*
1bab0 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
1bac0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1bad0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e  ite3_malloc() an
1bae0 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  d sqlite3_reallo
1baf0 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  c().** is always
1bb00 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c   aligned to at l
1bb10 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62  east an 8 byte b
1bb20 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61  oundary, or to a
1bb30 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64  .** 4 byte bound
1bb40 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49  ary if the [SQLI
1bb50 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45  TE_4_BYTE_ALIGNE
1bb60 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c  D_MALLOC] compil
1bb70 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
1bb80 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
1bb90 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  In SQLite versio
1bba0 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e  n 3.5.0 and 3.5.
1bbb0 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62  1, it was possib
1bbc0 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20  le to define.** 
1bbd0 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  the SQLITE_OMIT_
1bbe0 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f  MEMORY_ALLOCATIO
1bbf0 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61  N which would ca
1bc00 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  use the built-in
1bc10 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
1bc20 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  on of these rout
1bc30 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74  ines to be omitt
1bc40 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69  ed.  That capabi
1bc50 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f  lity.** is no lo
1bc60 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20  nger provided.  
1bc70 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65  Only built-in me
1bc80 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20  mory allocators 
1bc90 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a  can be used..**.
1bca0 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69  ** Prior to SQLi
1bcb0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31  te version 3.7.1
1bcc0 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20 4f  0, the Windows O
1bcd0 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
1bce0 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20  r called.** the 
1bcf0 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
1bd00 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63  and free() direc
1bd10 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74  tly when convert
1bd20 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73  ing.** filenames
1bd30 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46   between the UTF
1bd40 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  -8 encoding used
1bd50 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e   by SQLite.** an
1bd60 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e  d whatever filen
1bd70 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ame encoding is 
1bd80 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74  used by the part
1bd90 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a  icular Windows.*
1bda0 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20  * installation. 
1bdb0 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
1bdc0 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20 64  on errors were d
1bdd0 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20  etected, but.** 
1bde0 74 68 65 79 20 77 65 72 65 20 72 65 70 6f 72 74  they were report
1bdf0 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49  ed back as [SQLI
1be00 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a  TE_CANTOPEN] or.
1be10 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ** [SQLITE_IOERR
1be20 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53  ] rather than [S
1be30 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
1be40 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20  .** The pointer 
1be50 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71  arguments to [sq
1be60 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e  lite3_free()] an
1be70 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
1be80 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65  oc()].** must be
1be90 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20   either NULL or 
1bea0 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62  else pointers ob
1beb0 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72  tained from a pr
1bec0 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ior.** invocatio
1bed0 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
1bee0 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  lloc()] or [sqli
1bef0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74  te3_realloc()] t
1bf00 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20  hat have.** not 
1bf10 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65  yet been release
1bf20 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  d..**.** The app
1bf30 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
1bf40 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20  t read or write 
1bf50 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61  any part of.** a
1bf60 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
1bf70 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
1bf80 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e  en released usin
1bf90 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  g.** [sqlite3_fr
1bfa0 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ee()] or [sqlite
1bfb0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  3_realloc()]..*/
1bfc0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d  .void *sqlite3_m
1bfd0 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64  alloc(int);.void
1bfe0 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   *sqlite3_reallo
1bff0 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76  c(void*, int);.v
1c000 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
1c010 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  (void*);../*.** 
1c020 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
1c030 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69   Allocator Stati
1c040 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  stics.**.** SQLi
1c050 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73  te provides thes
1c060 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73  e two interfaces
1c070 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f   for reporting o
1c080 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20  n the status.** 
1c090 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
1c0a0 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69  malloc()], [sqli
1c0b0 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64  te3_free()], and
1c0c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1c0d0 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  c()].** routines
1c0e0 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65  , which form the
1c0f0 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
1c100 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
1c110 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ystem..**.** ^Th
1c120 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
1c130 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e  y_used()] routin
1c140 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
1c150 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a  mber of bytes.**
1c160 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65   of memory curre
1c170 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67  ntly outstanding
1c180 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e   (malloced but n
1c190 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54  ot freed)..** ^T
1c1a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
1c1b0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1c1c0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1c1d0 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76  the maximum.** v
1c1e0 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
1c1f0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1c200 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77  since the high-w
1c210 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73  ater mark.** was
1c220 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54   last reset.  ^T
1c230 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
1c240 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ed by [sqlite3_m
1c250 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e  emory_used()] an
1c260 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d.** [sqlite3_me
1c270 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1c280 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76  ] include any ov
1c290 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20  erhead.** added 
1c2a0 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73  by SQLite in its
1c2b0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1c2c0 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
1c2d0 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f  oc()],.** but no
1c2e0 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64  t overhead added
1c2f0 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65   by the any unde
1c300 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69  rlying system li
1c310 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65  brary.** routine
1c320 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  s that [sqlite3_
1c330 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61  malloc()] may ca
1c340 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ll..**.** ^The m
1c350 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72  emory high-water
1c360 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74   mark is reset t
1c370 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  o the current va
1c380 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74  lue of.** [sqlit
1c390 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1c3a0 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  ] if and only if
1c3b0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74   the parameter t
1c3c0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  o.** [sqlite3_me
1c3d0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1c3e0 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65  ] is true.  ^The
1c3f0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
1c400 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ** by [sqlite3_m
1c410 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1c420 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d  1)] is the high-
1c430 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72  water mark.** pr
1c440 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74  ior to the reset
1c450 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
1c460 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
1c470 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71  y_used(void);.sq
1c480 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
1c490 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1c4a0 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c  ater(int resetFl
1c4b0 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ag);../*.** CAPI
1c4c0 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e  3REF: Pseudo-Ran
1c4d0 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72  dom Number Gener
1c4e0 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ator.**.** SQLit
1c4f0 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67  e contains a hig
1c500 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f  h-quality pseudo
1c510 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67  -random number g
1c520 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20  enerator (PRNG) 
1c530 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63  used to.** selec
1c540 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20  t random [ROWID 
1c550 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69  | ROWIDs] when i
1c560 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63  nserting new rec
1c570 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c  ords into a tabl
1c580 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64  e that.** alread
1c590 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65  y uses the large
1c5a0 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57  st possible [ROW
1c5b0 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69  ID].  The PRNG i
1c5c0 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a  s also used for.
1c5d0 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20  ** the build-in 
1c5e0 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e  random() and ran
1c5f0 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75  domblob() SQL fu
1c600 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69  nctions.  This i
1c610 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a  nterface allows.
1c620 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
1c630 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61  to access the sa
1c640 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65  me PRNG for othe
1c650 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a  r purposes..**.*
1c660 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69  * ^A call to thi
1c670 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
1c680 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64   N bytes of rand
1c690 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66  omness into buff
1c6a0 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er P..**.** ^The
1c6b0 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73   first time this
1c6c0 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f   routine is invo
1c6d0 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 65  ked (either inte
1c6e0 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20  rnally or by.** 
1c6f0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29  the application)
1c700 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65   the PRNG is see
1c710 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d  ded using random
1c720 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ness obtained.**
1c730 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f   from the xRando
1c740 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  mness method of 
1c750 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
1c760 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
1c770 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62  ..** ^On all sub
1c780 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
1c790 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d  ons, the pseudo-
1c7a0 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65  randomness is ge
1c7b0 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72  nerated.** inter
1c7c0 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75  nally and withou
1c7d0 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68  t recourse to th
1c7e0 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
1c7f0 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d  xRandomness.** m
1c800 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73  ethod..*/.void s
1c810 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73  qlite3_randomnes
1c820 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50  s(int N, void *P
1c830 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1c840 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65  EF: Compile-Time
1c850 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43   Authorization C
1c860 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
1c870 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67  This routine reg
1c880 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72  isters an author
1c890 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
1c8a0 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
1c8b0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1c8c0 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69  nection], suppli
1c8d0 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
1c8e0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
1c8f0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1c900 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1c910 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
1c920 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d  ts are being com
1c930 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  piled.** by [sql
1c940 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
1c950 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  or its variants 
1c960 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1c970 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
1c980 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
1c990 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
1c9a0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20  epare16_v2()].  
1c9b0 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70  ^At various.** p
1c9c0 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65  oints during the
1c9d0 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f   compilation pro
1c9e0 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69  cess, as logic i
1c9f0 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a  s being created.
1ca00 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ** to perform va
1ca10 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74  rious actions, t
1ca20 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1ca30 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1ca40 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74  d to.** see if t
1ca50 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65  hose actions are
1ca60 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20   allowed.  ^The 
1ca70 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1ca80 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ack should.** re
1ca90 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
1caa0 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63   to allow the ac
1cab0 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47  tion, [SQLITE_IG
1cac0 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f  NORE] to disallo
1cad0 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  w the.** specifi
1cae0 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c  c action but all
1caf0 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ow the SQL state
1cb00 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65  ment to continue
1cb10 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c   to be.** compil
1cb20 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  ed, or [SQLITE_D
1cb30 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68  ENY] to cause th
1cb40 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61  e entire SQL sta
1cb50 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20  tement to be.** 
1cb60 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e  rejected with an
1cb70 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65   error.  ^If the
1cb80 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1cb90 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
1cba0 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20  any value other 
1cbb0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e  than [SQLITE_IGN
1cbc0 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  ORE], [SQLITE_OK
1cbd0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  ], or [SQLITE_DE
1cbe0 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  NY].** then the 
1cbf0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1cc00 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
1cc10 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
1cc20 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20  riggered.** the 
1cc30 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
1cc40 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
1cc50 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
1cc60 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  * When the callb
1cc70 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
1cc80 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65  ITE_OK], that me
1cc90 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ans the operatio
1cca0 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69  n.** requested i
1ccb0 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65  s ok.  ^When the
1ccc0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1ccd0 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c  s [SQLITE_DENY],
1cce0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1ccf0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1cd00 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
1cd10 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
1cd20 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
1cd30 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
1cd40 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
1cd50 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68  ge explaining th
1cd60 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20  at.** access is 
1cd70 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e  denied. .**.** ^
1cd80 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
1cd90 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
1cda0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1cdb0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
1cdc0 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
1cdd0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
1cde0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1cdf0 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54  () interface. ^T
1ce00 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1ce10 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ter.** to the ca
1ce20 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
1ce30 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50  eger [SQLITE_COP
1ce40 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d  Y | action code]
1ce50 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
1ce60 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  ** the particula
1ce70 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  r action to be a
1ce80 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20  uthorized. ^The 
1ce90 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
1cea0 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  xth parameters.*
1ceb0 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
1cec0 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69  k are zero-termi
1ced0 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
1cee0 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74  at contain addit
1cef0 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73  ional.** details
1cf00 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
1cf10 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
1cf20 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
1cf30 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
1cf40 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a   [SQLITE_READ].*
1cf50 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  * and the callba
1cf60 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
1cf70 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
1cf80 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
1cf90 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74   statement] stat
1cfa0 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75  ement is constru
1cfb0 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75  cted to substitu
1cfc0 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c  te.** a NULL val
1cfd0 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  ue in place of t
1cfe0 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
1cff0 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a  that would have.
1d000 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20  ** been read if 
1d010 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20  [SQLITE_OK] had 
1d020 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20  been returned.  
1d030 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  The [SQLITE_IGNO
1d040 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61  RE].** return ca
1d050 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e  n be used to den
1d060 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75  y an untrusted u
1d070 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e  ser access to in
1d080 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75  dividual.** colu
1d090 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a  mns of a table..
1d0a0 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
1d0b0 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
1d0c0 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68  E_DELETE] and th
1d0d0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1d0e0 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47  ns.** [SQLITE_IG
1d0f0 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b  NORE] then the [
1d100 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f  DELETE] operatio
1d110 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74  n proceeds but t
1d120 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20  he.** [truncate 
1d130 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73  optimization] is
1d140 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c   disabled and al
1d150 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  l rows are delet
1d160 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e  ed individually.
1d170 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72  .**.** An author
1d180 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65  izer is used whe
1d190 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
1d1a0 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a  re | preparing].
1d1b0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1d1c0 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73  s from an untrus
1d1d0 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65  ted source, to e
1d1e0 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53  nsure that the S
1d1f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
1d200 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61   do not try to a
1d210 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20  ccess data they 
1d220 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20  are not allowed 
1d230 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20  to see, or that 
1d240 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74  they do not.** t
1d250 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61  ry to execute ma
1d260 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e  licious statemen
1d270 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74  ts that damage t
1d280 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f  he database.  Fo
1d290 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e  r.** example, an
1d2a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
1d2b0 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f   allow a user to
1d2c0 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79   enter arbitrary
1d2d0 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20  .** SQL queries 
1d2e0 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62  for evaluation b
1d2f0 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42  y a database.  B
1d300 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ut the applicati
1d310 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  on does.** not w
1d320 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20  ant the user to 
1d330 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20  be able to make 
1d340 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65  arbitrary change
1d350 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
1d360 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72  base.  An author
1d370 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20  izer could then 
1d380 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20  be put in place 
1d390 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65  while the.** use
1d3a0 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73  r-entered SQL is
1d3b0 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   being [sqlite3_
1d3c0 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
1d3d0 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61  ed] that.** disa
1d3e0 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67  llows everything
1d3f0 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d   except [SELECT]
1d400 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
1d410 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
1d420 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f  that need to pro
1d430 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e  cess SQL from un
1d440 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a  trusted sources.
1d450 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f  ** might also co
1d460 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20  nsider lowering 
1d470 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20  resource limits 
1d480 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
1d490 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c  imit()].** and l
1d4a0 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65  imiting database
1d4b0 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20   size using the 
1d4c0 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
1d4d0 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20   [PRAGMA].** in 
1d4e0 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e  addition to usin
1d4f0 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e  g an authorizer.
1d500 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20  .**.** ^(Only a 
1d510 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65  single authorize
1d520 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63  r can be in plac
1d530 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  e on a database 
1d540 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74  connection.** at
1d550 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63   a time.  Each c
1d560 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
1d570 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76  et_authorizer ov
1d580 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70  errides the.** p
1d590 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20  revious call.)^ 
1d5a0 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75   ^Disable the au
1d5b0 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74  thorizer by inst
1d5c0 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61  alling a NULL ca
1d5d0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61  llback..** The a
1d5e0 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73  uthorizer is dis
1d5f0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
1d600 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  ..**.** The auth
1d610 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1d620 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
1d630 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
1d640 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
1d650 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d660 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1d670 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1d680 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74  lback..** Note t
1d690 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
1d6a0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
1d6b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1d6c0 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
1d6d0 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
1d6e0 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
1d6f0 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
1d700 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
1d710 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e  ragraph..**.** ^
1d720 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  When [sqlite3_pr
1d730 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75  epare_v2()] is u
1d740 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61  sed to prepare a
1d750 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a   statement, the.
1d760 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67  ** statement mig
1d770 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65  ht be re-prepare
1d780 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65  d during [sqlite
1d790 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f  3_step()] due to
1d7a0 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68   a .** schema ch
1d7b0 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68  ange.  Hence, th
1d7c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
1d7d0 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74  ould ensure that
1d7e0 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20   the.** correct 
1d7f0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1d800 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70  ack remains in p
1d810 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20  lace during the 
1d820 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1d830 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68  ..**.** ^Note th
1d840 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  at the authorize
1d850 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
1d860 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e  voked only durin
1d870 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  g.** [sqlite3_pr
1d880 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
1d890 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f  variants.  Autho
1d8a0 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a  rization is not.
1d8b0 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72  ** performed dur
1d8c0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76  ing statement ev
1d8d0 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c  aluation in [sql
1d8e0 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e  ite3_step()], un
1d8f0 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65  less.** as state
1d900 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  d in the previou
1d910 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c  s paragraph, sql
1d920 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f  ite3_step() invo
1d930 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  kes.** sqlite3_p
1d940 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72  repare_v2() to r
1d950 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65  eprepare a state
1d960 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68  ment after a sch
1d970 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69  ema change..*/.i
1d980 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  nt sqlite3_set_a
1d990 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c  uthorizer(.  sql
1d9a0 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78  ite3*,.  int (*x
1d9b0 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  Auth)(void*,int,
1d9c0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
1d9d0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
1d9e0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  ar*,const char*)
1d9f0 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44  ,.  void *pUserD
1da00 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ata.);../*.** CA
1da10 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
1da20 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a  er Return Codes.
1da30 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
1da40 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1da50 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
1da60 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1da70 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e  ] must.** return
1da80 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
1da90 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  OK] or one of th
1daa0 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74  ese two constant
1dab0 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f  s in order.** to
1dac0 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77   signal SQLite w
1dad0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
1dae0 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  e action is perm
1daf0 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a  itted.  See the.
1db00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  ** [sqlite3_set_
1db10 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
1db20 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74  horizer document
1db30 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74  ation] for addit
1db40 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
1db50 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  tion..**.** Note
1db60 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e   that SQLITE_IGN
1db70 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64  ORE is also used
1db80 20 61 73 20 61 20 5b 53 51 4c 49 54 45 5f 52 4f   as a [SQLITE_RO
1db90 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75 72 6e 20  LLBACK | return 
1dba0 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68  code].** from th
1dbb0 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  e [sqlite3_vtab_
1dbc0 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69  on_conflict()] i
1dbd0 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65  nterface..*/.#de
1dbe0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59  fine SQLITE_DENY
1dbf0 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20     1   /* Abort 
1dc00 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1dc10 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  t with an error 
1dc20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1dc30 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20  E_IGNORE 2   /* 
1dc40 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65  Don't allow acce
1dc50 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65  ss, but don't ge
1dc60 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20  nerate an error 
1dc70 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
1dc80 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41  EF: Authorizer A
1dc90 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  ction Codes.**.*
1dca0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
1dcb0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
1dcc0 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
1dcd0 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ters a callback 
1dce0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  function.** that
1dcf0 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61   is invoked to a
1dd00 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e  uthorize certain
1dd10 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
1dd20 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20  ctions.  The.** 
1dd30 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1dd40 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
1dd50 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63   is an integer c
1dd60 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69  ode that specifi
1dd70 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f  es.** what actio
1dd80 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f  n is being autho
1dd90 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72  rized.  These ar
1dda0 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63  e the integer ac
1ddb0 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a  tion codes that.
1ddc0 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
1ddd0 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62  r callback may b
1dde0 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  e passed..**.** 
1ddf0 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64  These action cod
1de00 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79  e values signify
1de10 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70   what kind of op
1de20 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  eration is to be
1de30 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  .** authorized. 
1de40 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68   The 3rd and 4th
1de50 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
1de60 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  he authorization
1de70 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
1de80 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61  ction will be pa
1de90 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c  rameters or NULL
1dea0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68   depending on wh
1deb0 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ich of these.** 
1dec0 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73  codes is used as
1ded0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1dee0 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74  meter.  ^(The 5t
1def0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
1df00 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
1df10 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
1df20 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
1df30 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22  abase ("main", "
1df40 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20  temp",.** etc.) 
1df50 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e  if applicable.)^
1df60 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d    ^The 6th param
1df70 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
1df80 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a  orizer callback.
1df90 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
1dfa0 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74  f the inner-most
1dfb0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77   trigger or view
1dfc0 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73   that is respons
1dfd0 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ible for.** the 
1dfe0 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f  access attempt o
1dff0 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61  r NULL if this a
1e000 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73  ccess attempt is
1e010 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a   directly from.*
1e020 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20  * top-level SQL 
1e030 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  code..*/./******
1e040 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e050 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e060 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a  ***** 3rd ******
1e070 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a  ****** 4th *****
1e080 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20  ******/.#define 
1e090 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e  SQLITE_CREATE_IN
1e0a0 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20  DEX          1  
1e0b0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1e0c0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1e0d0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1e0e0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42  QLITE_CREATE_TAB
1e0f0 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20  LE          2   
1e100 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1e110 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1e120 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1e130 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1e140 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f  _INDEX     3   /
1e150 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1e160 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1e170 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1e180 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1e190 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a  TABLE     4   /*
1e1a0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1e1b0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1e1c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e1d0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
1e1e0 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20  RIGGER   5   /* 
1e1f0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1e200 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1e210 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e220 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49  E_CREATE_TEMP_VI
1e230 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56  EW      6   /* V
1e240 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1e250 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1e260 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e270 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20  _CREATE_TRIGGER 
1e280 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72         7   /* Tr
1e290 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1e2a0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1e2b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e2c0 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20  CREATE_VIEW     
1e2d0 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65        8   /* Vie
1e2e0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1e2f0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1e300 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1e310 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
1e320 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c       9   /* Tabl
1e330 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1e340 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1e350 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1e360 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  OP_INDEX        
1e370 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78     10   /* Index
1e380 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1e390 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1e3a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1e3b0 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  P_TABLE         
1e3c0 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20    11   /* Table 
1e3d0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1e3e0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1e3f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1e400 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
1e410 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   12   /* Index N
1e420 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1e430 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1e440 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1e450 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20  TEMP_TABLE      
1e460 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  13   /* Table Na
1e470 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1e480 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1e490 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1e4a0 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31  EMP_TRIGGER    1
1e4b0 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  4   /* Trigger N
1e4c0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1e4d0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1e4e0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
1e4f0 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35  MP_VIEW       15
1e500 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1e510 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1e520 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1e530 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49   SQLITE_DROP_TRI
1e540 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20  GGER         16 
1e550 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1e560 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1e570 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1e580 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57  SQLITE_DROP_VIEW
1e590 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20              17  
1e5a0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1e5b0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1e5c0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1e5d0 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20  QLITE_INSERT    
1e5e0 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20             18   
1e5f0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1e600 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1e610 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1e620 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20  LITE_PRAGMA     
1e630 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f            19   /
1e640 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20  * Pragma Name   
1e650 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c    1st arg or NUL
1e660 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  L */.#define SQL
1e670 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20  ITE_READ        
1e680 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a           20   /*
1e690 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1e6a0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
1e6b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e6c0 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  TE_SELECT       
1e6d0 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20          21   /* 
1e6e0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1e6f0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1e700 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e710 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20  E_TRANSACTION   
1e720 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f         22   /* O
1e730 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e  peration       N
1e740 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1e750 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1e760 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20  _UPDATE         
1e770 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61        23   /* Ta
1e780 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
1e790 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
1e7a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e7b0 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20  ATTACH          
1e7c0 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c       24   /* Fil
1e7d0 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c  ename        NUL
1e7e0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1e7f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1e800 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  ETACH           
1e810 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61      25   /* Data
1e820 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c  base Name   NULL
1e830 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1e840 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c  define SQLITE_AL
1e850 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20  TER_TABLE       
1e860 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62     26   /* Datab
1e870 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65  ase Name   Table
1e880 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1e890 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49  efine SQLITE_REI
1e8a0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20  NDEX            
1e8b0 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20    27   /* Index 
1e8c0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1e8d0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1e8e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c  fine SQLITE_ANAL
1e8f0 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  YZE             
1e900 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   28   /* Table N
1e910 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1e920 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1e930 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1e940 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  E_VTABLE        
1e950 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  29   /* Table Na
1e960 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
1e970 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
1e980 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
1e990 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33  TABLE          3
1e9a0 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
1e9b0 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
1e9c0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1e9d0 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f  e SQLITE_FUNCTIO
1e9e0 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31  N             31
1e9f0 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
1ea00 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e        Function N
1ea10 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  ame   */.#define
1ea20 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e   SQLITE_SAVEPOIN
1ea30 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20  T            32 
1ea40 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
1ea50 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e       Savepoint N
1ea60 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ame  */.#define 
1ea70 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20  SQLITE_COPY     
1ea80 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20               0  
1ea90 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73   /* No longer us
1eaa0 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
1eab0 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41  I3REF: Tracing A
1eac0 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e  nd Profiling Fun
1ead0 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
1eae0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
1eaf0 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
1eb00 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
1eb10 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
1eb20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
1eb30 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
1eb40 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
1eb50 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
1eb60 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
1eb70 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
1eb80 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  y sqlite3_trace(
1eb90 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a  ) is invoked at.
1eba0 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73  ** various times
1ebb0 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61   when an SQL sta
1ebc0 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20  tement is being 
1ebd0 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  run by [sqlite3_
1ebe0 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  step()]..** ^The
1ebf0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
1ec00 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1ec10 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d  oked with a UTF-
1ec20 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  8 rendering of t
1ec30 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  he.** SQL statem
1ec40 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20  ent text as the 
1ec50 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20  statement first 
1ec60 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67  begins executing
1ec70 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61  ..** ^(Additiona
1ec80 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  l sqlite3_trace(
1ec90 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68  ) callbacks migh
1eca0 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61  t occur.** as ea
1ecb0 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62  ch triggered sub
1ecc0 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72  program is enter
1ecd0 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63  ed.  The callbac
1ece0 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a  ks for triggers.
1ecf0 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46  ** contain a UTF
1ed00 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74  -8 SQL comment t
1ed10 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74  hat identifies t
1ed20 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a  he trigger.)^.**
1ed30 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
1ed40 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54  TRACE_SIZE_LIMIT
1ed50 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1ed60 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
1ed70 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68  d to limit.** th
1ed80 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75  e length of [bou
1ed90 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78  nd parameter] ex
1eda0 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f  pansion in the o
1edb0 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33  utput of sqlite3
1edc0 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  _trace()..**.** 
1edd0 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
1ede0 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
1edf0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f  d by sqlite3_pro
1ee00 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  file() is invoke
1ee10 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c  d.** as each SQL
1ee20 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
1ee30 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  hes.  ^The profi
1ee40 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  le callback cont
1ee50 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67  ains.** the orig
1ee60 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74  inal statement t
1ee70 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d  ext and an estim
1ee80 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63  ate of wall-cloc
1ee90 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77  k time.** of how
1eea0 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65   long that state
1eeb0 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e  ment took to run
1eec0 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
1eed0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65  callback.** time
1eee0 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20   is in units of 
1eef0 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77  nanoseconds, how
1ef00 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74  ever the current
1ef10 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
1ef20 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62  ** is only capab
1ef30 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  le of millisecon
1ef40 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20  d resolution so 
1ef50 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69  the six least si
1ef60 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67  gnificant.** dig
1ef70 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20  its in the time 
1ef80 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e  are meaningless.
1ef90 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
1efa0 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d  s of SQLite.** m
1efb0 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65  ight provide gre
1efc0 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20  ater resolution 
1efd0 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20  on the profiler 
1efe0 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a  callback.  The.*
1eff0 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  * sqlite3_profil
1f000 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
1f010 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72  considered exper
1f020 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a  imental and is.*
1f030 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  * subject to cha
1f040 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65  nge in future ve
1f050 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1f060 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
1f070 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33  e3_trace(sqlite3
1f080 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29  *, void(*xTrace)
1f090 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
1f0a0 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c  r*), void*);.SQL
1f0b0 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
1f0c0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70   void *sqlite3_p
1f0d0 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c  rofile(sqlite3*,
1f0e0 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69  .   void(*xProfi
1f0f0 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  le)(void*,const 
1f100 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69  char*,sqlite3_ui
1f110 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  nt64), void*);..
1f120 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1f130 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43  Query Progress C
1f140 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
1f150 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  The sqlite3_prog
1f160 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e  ress_handler(D,N
1f170 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20  ,X,P) interface 
1f180 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62  causes the callb
1f190 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
1f1a0 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  X to be invoked 
1f1b0 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72  periodically dur
1f1c0 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67  ing long running
1f1d0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
1f1e0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b  lite3_exec()], [
1f1f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1f200 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  and [sqlite3_get
1f210 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a  _table()] for.**
1f220 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1f230 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d  tion D.  An exam
1f240 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73  ple use for this
1f250 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
1f260 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75   to keep a GUI u
1f270 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20  pdated during a 
1f280 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a  large query..**.
1f290 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  ** ^The paramete
1f2a0 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68  r P is passed th
1f2b0 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c  rough as the onl
1f2c0 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  y parameter to t
1f2d0 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  he .** callback 
1f2e0 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68  function X.  ^Th
1f2f0 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73  e parameter N is
1f300 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65   the approximate
1f310 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b   number of .** [
1f320 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
1f330 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68  instructions] th
1f340 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  at are evaluated
1f350 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73   between success
1f360 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ive.** invocatio
1f370 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61  ns of the callba
1f380 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20  ck X.  ^If N is 
1f390 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68  less than one th
1f3a0 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a  en the progress.
1f3b0 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69  ** handler is di
1f3c0 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  sabled..**.** ^O
1f3d0 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f  nly a single pro
1f3e0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61  gress handler ma
1f3f0 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20  y be defined at 
1f400 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20  one time per.** 
1f410 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1f420 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61  tion]; setting a
1f430 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61   new progress ha
1f440 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68  ndler cancels th
1f450 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e  e.** old one.  ^
1f460 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65  Setting paramete
1f470 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61  r X to NULL disa
1f480 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73  bles the progres
1f490 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54  s handler..** ^T
1f4a0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
1f4b0 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61  ler is also disa
1f4c0 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20  bled by setting 
1f4d0 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73  N to a value les
1f4e0 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a  s.** than 1..**.
1f4f0 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72  ** ^If the progr
1f500 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ess callback ret
1f510 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
1f520 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a  he operation is.
1f530 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20  ** interrupted. 
1f540 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61   This feature ca
1f550 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70  n be used to imp
1f560 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e  lement a.** "Can
1f570 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61  cel" button on a
1f580 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69   GUI progress di
1f590 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20  alog box..**.** 
1f5a0 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
1f5b0 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  dler callback mu
1f5c0 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
1f5d0 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
1f5e0 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
1f5f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
1f600 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
1f610 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1f620 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
1f630 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1f640 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
1f650 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
1f660 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
1f670 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1f680 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
1f690 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
1f6a0 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
1f6b0 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73  ph..**.*/.void s
1f6c0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
1f6d0 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
1f6e0 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f  , int, int(*)(vo
1f6f0 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  id*), void*);../
1f700 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
1f710 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74  pening A New Dat
1f720 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
1f730 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
1f740 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53  utines open an S
1f750 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
1f760 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64  ile as specified
1f770 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65   by the .** file
1f780 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e  name argument. ^
1f790 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  The filename arg
1f7a0 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72  ument is interpr
1f7b0 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f  eted as UTF-8 fo
1f7c0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
1f7d0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
1f7e0 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73  open_v2() and as
1f7f0 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
1f800 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72  ative byte.** or
1f810 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
1f820 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64  open16(). ^(A [d
1f830 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1f840 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73  on] handle is us
1f850 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65  ually.** returne
1f860 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e  d in *ppDb, even
1f870 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63   if an error occ
1f880 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65  urs.  The only e
1f890 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74  xception is that
1f8a0 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73  .** if SQLite is
1f8b0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
1f8c0 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  ate memory to ho
1f8d0 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  ld the [sqlite3]
1f8e0 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55   object,.** a NU
1f8f0 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74  LL will be writt
1f900 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e  en into *ppDb in
1f910 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74  stead of a point
1f920 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
1f930 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e  e3].** object.)^
1f940 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61   ^(If the databa
1f950 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e  se is opened (an
1f960 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75  d/or created) su
1f970 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e  ccessfully, then
1f980 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  .** [SQLITE_OK] 
1f990 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
1f9a0 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
1f9b0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
1f9c0 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b  ned.)^ ^The.** [
1f9d0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1f9e0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  ] or [sqlite3_er
1f9f0 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e  rmsg16()] routin
1fa00 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  es can be used t
1fa10 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45  o obtain.** an E
1fa20 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20  nglish language 
1fa30 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74  description of t
1fa40 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69  he error followi
1fa50 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20  ng a failure of 
1fa60 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  any.** of the sq
1fa70 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75  lite3_open() rou
1fa80 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tines..**.** ^Th
1fa90 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
1faa0 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  ng for the datab
1fab0 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ase will be UTF-
1fac0 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  8 if.** sqlite3_
1fad0 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
1fae0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63  3_open_v2() is c
1faf0 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46  alled and.** UTF
1fb00 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
1fb10 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20  e byte order if 
1fb20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1fb30 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
1fb40 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61  Whether or not a
1fb50 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77  n error occurs w
1fb60 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64  hen it is opened
1fb70 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61  , resources.** a
1fb80 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1fb90 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
1fba0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
1fbb0 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73  should be releas
1fbc0 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67  ed by.** passing
1fbd0 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
1fbe0 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74  close()] when it
1fbf0 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65   is no longer re
1fc00 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  quired..**.** Th
1fc10 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  e sqlite3_open_v
1fc20 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f  2() interface wo
1fc30 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
1fc40 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70  _open().** excep
1fc50 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74  t that it accept
1fc60 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  s two additional
1fc70 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20   parameters for 
1fc80 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72  additional contr
1fc90 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e  ol.** over the n
1fca0 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
1fcb0 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66  ection.  ^(The f
1fcc0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
1fcd0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
1fce0 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20  n_v2() can take 
1fcf0 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f  one of.** the fo
1fd00 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61  llowing three va
1fd10 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79  lues, optionally
1fd20 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74   combined with t
1fd30 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  he .** [SQLITE_O
1fd40 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53  PEN_NOMUTEX], [S
1fd50 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
1fd60 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
1fd70 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
1fd80 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ,.** [SQLITE_OPE
1fd90 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c  N_PRIVATECACHE],
1fda0 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f   and/or [SQLITE_
1fdb0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a  OPEN_URI] flags:
1fdc0 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  )^.**.** <dl>.**
1fdd0 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
1fde0 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64  PEN_READONLY]</d
1fdf0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
1fe00 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1fe10 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f   in read-only mo
1fe20 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61  de.  If the data
1fe30 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  base does not.**
1fe40 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
1fe50 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
1fe60 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
1fe70 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
1fe80 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
1fe90 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1fea0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1feb0 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
1fec0 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70  and writing if p
1fed0 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64  ossible, or read
1fee0 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74  ing.** only if t
1fef0 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65  he file is write
1ff00 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68   protected by th
1ff10 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
1ff20 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a  em.  In either.*
1ff30 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62  * case the datab
1ff40 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79  ase must already
1ff50 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73   exist, otherwis
1ff60 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  e an error is re
1ff70 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
1ff80 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
1ff90 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
1ffa0 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
1ffb0 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a  N_CREATE]</dt>.*
1ffc0 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
1ffd0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
1ffe0 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
1fff0 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65  ting, and is cre
20000 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f  ated if.** it do
20010 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65  es not already e
20020 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68  xist. This is th
20030 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20  e behavior that 
20040 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66  is always used f
20050 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
20060 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
20070 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29  _open16().</dd>)
20080 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a  ^.** </dl>.**.**
20090 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
200a0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
200b0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f  _open_v2() is no
200c0 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  t one of the.** 
200d0 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f  combinations sho
200e0 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61  wn above optiona
200f0 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
20100 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49  h other.** [SQLI
20110 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
20120 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a   | SQLITE_OPEN_*
20130 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74   bits].** then t
20140 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
20150 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
20160 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
20170 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c  OPEN_NOMUTEX] fl
20180 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20  ag is set, then 
20190 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
201a0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73  nection.** opens
201b0 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68   in the multi-th
201c0 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
201d0 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73  mode] as long as
201e0 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65   the single-thre
201f0 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e  ad.** mode has n
20200 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63  ot been set at c
20210 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
20220 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20  tart-time.  ^If 
20230 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  the.** [SQLITE_O
20240 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66  PEN_FULLMUTEX] f
20250 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20  lag is set then 
20260 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
20270 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a  nection opens.**
20280 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a   in the serializ
20290 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
202a0 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c  de] unless singl
202b0 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20  e-thread was.** 
202c0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63  previously selec
202d0 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  ted at compile-t
202e0 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
202f0 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  e..** ^The [SQLI
20300 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
20310 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
20320 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
20330 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  nnection to be.*
20340 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73  * eligible to us
20350 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  e [shared cache 
20360 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73  mode], regardles
20370 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
20380 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  not shared.** ca
20390 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75  che is enabled u
203a0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e  sing [sqlite3_en
203b0 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
203c0 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b  e()].  ^The.** [
203d0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
203e0 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63  ATECACHE] flag c
203f0 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
20400 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
20410 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70   not.** particip
20420 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63  ate in [shared c
20430 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20  ache mode] even 
20440 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64  if it is enabled
20450 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
20460 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
20470 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
20480 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  () is the name o
20490 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
204a0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68  3_vfs] object th
204b0 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f  at defines the o
204c0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
204d0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a  interface that.*
204e0 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  * the new databa
204f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68  se connection sh
20500 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74  ould use.  ^If t
20510 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
20520 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c  ter is.** a NULL
20530 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
20540 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
20550 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69  e3_vfs] object i
20560 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s used..**.** ^I
20570 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
20580 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68  s ":memory:", th
20590 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
205a0 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72  mporary in-memor
205b0 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73  y database.** is
205c0 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65   created for the
205d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54   connection.  ^T
205e0 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  his in-memory da
205f0 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69  tabase will vani
20600 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64  sh when.** the d
20610 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20620 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46  on is closed.  F
20630 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
20640 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a  f SQLite might.*
20650 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64  * make use of ad
20660 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c  ditional special
20670 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20   filenames that 
20680 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22  begin with the "
20690 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  :" character..**
206a0 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   It is recommend
206b0 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64  ed that when a d
206c0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
206d0 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62   actually does b
206e0 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22  egin with.** a "
206f0 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75  :" character you
20700 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74   should prefix t
20710 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68  he filename with
20720 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68   a pathname such
20730 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61   as.** "./" to a
20740 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a  void ambiguity..
20750 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
20760 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70  lename is an emp
20770 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  ty string, then 
20780 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
20790 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20  rary.** on-disk 
207a0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
207b0 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73   created.  ^This
207c0 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73   private databas
207d0 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74  e will be.** aut
207e0 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
207f0 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68  ed as soon as th
20800 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
20810 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
20820 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c  .**.** [[URI fil
20830 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65  enames in sqlite
20840 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55  3_open()]] <h3>U
20850 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33  RI Filenames</h3
20860 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49  >.**.** ^If [URI
20870 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72   filename] inter
20880 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61  pretation is ena
20890 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69  bled, and the fi
208a0 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a  lename argument.
208b0 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22  ** begins with "
208c0 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65  file:", then the
208d0 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74   filename is int
208e0 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52  erpreted as a UR
208f0 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e  I. ^URI.** filen
20900 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
20910 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66  on is enabled if
20920 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
20930 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a  N_URI] flag is.*
20940 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75  * set in the fou
20950 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
20960 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
20970 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a  ), or if it has.
20980 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20  ** been enabled 
20990 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74  globally using t
209a0 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
209b0 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69  G_URI] option wi
209c0 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  th the.** [sqlit
209d0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74  e3_config()] met
209e0 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53  hod or by the [S
209f0 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63  QLITE_USE_URI] c
20a00 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
20a10 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c  on..** As of SQL
20a20 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
20a30 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  7, URI filename 
20a40 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
20a50 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20  s turned off.** 
20a60 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20  by default, but 
20a70 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
20a80 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
20a90 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e  enable URI filen
20aa0 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ame.** interpret
20ab0 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74  ation by default
20ac0 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c  .  See "[URI fil
20ad0 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64  enames]" for add
20ae0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
20af0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52  mation..**.** UR
20b00 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20  I filenames are 
20b10 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67  parsed according
20b20 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49   to RFC 3986. ^I
20b30 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69  f the URI contai
20b40 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69  ns an.** authori
20b50 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74  ty, then it must
20b60 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d   be either an em
20b70 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68  pty string or th
20b80 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f  e string .** "lo
20b90 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68  calhost". ^If th
20ba0 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e  e authority is n
20bb0 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  ot an empty stri
20bc0 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74  ng or "localhost
20bd0 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20  ", an .** error 
20be0 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74  is returned to t
20bf0 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20  he caller. ^The 
20c00 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65  fragment compone
20c10 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20  nt of a URI, if 
20c20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20  .** present, is 
20c30 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
20c40 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
20c50 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  path component o
20c60 66 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65  f the URI as the
20c70 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73   name of the dis
20c80 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20  k file.** which 
20c90 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74  contains the dat
20ca0 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70  abase. ^If the p
20cb0 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20  ath begins with 
20cc0 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c  a '/' character,
20cd0 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20   .** then it is 
20ce0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
20cf0 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e  n absolute path.
20d00 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f   ^If the path do
20d10 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a  es not begin .**
20d20 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61   with a '/' (mea
20d30 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75  ning that the au
20d40 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20  thority section 
20d50 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
20d60 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e  the URI).** then
20d70 20 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74   the path is int
20d80 65 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65  erpreted as a re
20d90 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a  lative path. .**
20da0 20 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68   ^On windows, th
20db0 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e  e first componen
20dc0 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65  t of an absolute
20dd0 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64   path .** is a d
20de0 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69  rive specificati
20df0 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 0a  on (e.g. "C:")..
20e00 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49  **.** [[core URI
20e10 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
20e20 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79  s]].** The query
20e30 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
20e40 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  URI may contain 
20e50 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20  parameters that 
20e60 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a  are interpreted.
20e70 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c  ** either by SQL
20e80 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62  ite itself, or b
20e90 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f  y a [VFS | custo
20ea0 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  m VFS implementa
20eb0 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65  tion]..** SQLite
20ec0 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
20ed0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20  following three 
20ee0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
20ef0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
20f00 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62    <li> <b>vfs</b
20f10 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61  >: ^The "vfs" pa
20f20 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75  rameter may be u
20f30 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74  sed to specify t
20f40 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20  he name of.**   
20f50 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74    a VFS object t
20f60 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65  hat provides the
20f70 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
20f80 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
20f90 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62   should.**     b
20fa0 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73  e used to access
20fb0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
20fc0 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20  le on disk. ^If 
20fd0 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73  this option is s
20fe0 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20  et to.**     an 
20ff0 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65  empty string the
21000 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a   default VFS obj
21010 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70  ect is used. ^Sp
21020 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e  ecifying an unkn
21030 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69  own.**     VFS i
21040 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20  s an error. ^If 
21050 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
21060 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68  ) is used and th
21070 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a  e vfs option is.
21080 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20  **     present, 
21090 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65  then the VFS spe
210a0 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70  cified by the op
210b0 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65  tion takes prece
210c0 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20  dence over.**   
210d0 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73    the value pass
210e0 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68  ed as the fourth
210f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
21100 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
21110 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  .**.**   <li> <b
21120 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65  >mode</b>: ^(The
21130 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20   mode parameter 
21140 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69  may be set to ei
21150 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c  ther "ro", "rw",
21160 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f  .**     "rwc", o
21170 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65  r "memory". Atte
21180 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74  mpting to set it
21190 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61   to any other va
211a0 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e  lue is.**     an
211b0 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20   error)^. .**   
211c0 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70    ^If "ro" is sp
211d0 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68  ecified, then th
211e0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
211f0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e  ened for read-on
21200 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  ly .**     acces
21210 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68  s, just as if th
21220 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
21230 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61  EADONLY] flag ha
21240 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68  d been set in th
21250 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20  e .**     third 
21260 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
21270 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e  te3_open_v2(). ^
21280 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69  If the mode opti
21290 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a  on is set to .**
212a0 20 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20       "rw", then 
212b0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
212c0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d  opened for read-
212d0 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63  write (but not c
212e0 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61  reate) .**     a
212f0 63 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c  ccess, as if SQL
21300 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
21310 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49  TE (but not SQLI
21320 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20  TE_OPEN_CREATE) 
21330 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e  had .**     been
21340 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77   set. ^Value "rw
21350 63 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  c" is equivalent
21360 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68   to setting both
21370 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f   .**     SQLITE_
21380 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61  OPEN_READWRITE a
21390 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  nd SQLITE_OPEN_C
213a0 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20  REATE.  ^If the 
213b0 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  mode option is.*
213c0 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65  *     set to "me
213d0 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72  mory" then a pur
213e0 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  e [in-memory dat
213f0 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65  abase] that neve
21400 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f  r reads.**     o
21410 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69  r writes from di
21420 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20  sk is used. ^It 
21430 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73  is an error to s
21440 70 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66  pecify a value f
21450 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f  or.**     the mo
21460 64 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  de parameter tha
21470 74 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69  t is less restri
21480 63 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20  ctive than that 
21490 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
214a0 20 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61      the flags pa
214b0 73 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72  ssed in the thir
214c0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
214d0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
214e0 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  ..**.**   <li> <
214f0 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68  b>cache</b>: ^Th
21500 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65  e cache paramete
21510 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20  r may be set to 
21520 65 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20  either "shared" 
21530 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61  or.**     "priva
21540 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74  te". ^Setting it
21550 20 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20   to "shared" is 
21560 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
21570 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20  tting the.**    
21580 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
21590 52 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20  REDCACHE bit in 
215a0 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
215b0 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  nt passed to.** 
215c0 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e      sqlite3_open
215d0 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20  _v2(). ^Setting 
215e0 74 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65  the cache parame
215f0 74 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22  ter to "private"
21600 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69   is .**     equi
21610 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
21620 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  g the SQLITE_OPE
21630 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62  N_PRIVATECACHE b
21640 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73  it..**     ^If s
21650 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
21660 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65   is used and the
21670 20 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74   "cache" paramet
21680 65 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e  er is present in
21690 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69  .**     a URI fi
216a0 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75  lename, its valu
216b0 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20  e overrides any 
216c0 62 65 68 61 76 69 6f 72 20 72 65 71 75 65 73 74  behavior request
216d0 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a  ed by setting.**
216e0 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
216f0 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72  _PRIVATECACHE or
21700 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
21710 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a  REDCACHE flag..*
21720 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53  * </ul>.**.** ^S
21730 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b  pecifying an unk
21740 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69  nown parameter i
21750 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70  n the query comp
21760 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69  onent of a URI i
21770 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f  s not an.** erro
21780 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  r.  Future versi
21790 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
217a0 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61  ght understand a
217b0 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a  dditional query.
217c0 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ** parameters.  
217d0 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61  See "[query para
217e0 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63  meters with spec
217f0 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53  ial meaning to S
21800 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61  QLite]" for.** a
21810 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
21820 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  ation..**.** [[U
21830 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
21840 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66  ples]] <h3>URI f
21850 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
21860 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62  </h3>.**.** <tab
21870 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c  le border="1" al
21880 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70  ign=center cellp
21890 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72  adding=5>.** <tr
218a0 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61  ><th> URI filena
218b0 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73  mes <th> Results
218c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
218d0 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  e:data.db <td> .
218e0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
218f0 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
21900 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
21910 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  nt directory..**
21920 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
21930 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
21940 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20  b<br>.**        
21950 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66    file:///home/f
21960 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
21970 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
21980 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68  le://localhost/h
21990 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
219a0 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20   <br> <td> .**  
219b0 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
219c0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22   database file "
219d0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
219e0 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  db"..** <tr><td>
219f0 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72   file://darkstar
21a00 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
21a10 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
21a20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22       An error. "
21a30 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74  darkstar" is not
21a40 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75   a recognized au
21a50 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e  thority..** <tr>
21a60 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65  <td style="white
21a70 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20  -space:nowrap"> 
21a80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
21a90 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74  e:///C:/Document
21aa0 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e  s%20and%20Settin
21ab0 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f  gs/fred/Desktop/
21ac0 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c  data.db.**     <
21ad0 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79  td> Windows only
21ae0 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20  : Open the file 
21af0 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65  "data.db" on fre
21b00 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64  d's desktop on d
21b10 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  rive.**         
21b20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74   C:. Note that t
21b30 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20  he %20 escaping 
21b40 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20  in this example 
21b50 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  is not strictly 
21b60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63  .**          nec
21b70 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63  essary - space c
21b80 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65  haracters can be
21b90 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a   used literally.
21ba0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55  **          in U
21bb0 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a  RI filenames..**
21bc0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
21bd0 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63  ata.db?mode=ro&c
21be0 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64  ache=private <td
21bf0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
21c00 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64  pen file "data.d
21c10 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
21c20 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20  t directory for 
21c30 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73  read-only access
21c40 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65  ..**          Re
21c50 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
21c60 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
21c70 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20  d-cache mode is 
21c80 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20  enabled by.**   
21c90 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20         default, 
21ca0 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61  use a private ca
21cb0 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  che..** <tr><td>
21cc0 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
21cd0 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69  /data.db?vfs=uni
21ce0 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a  x-nolock <td>.**
21cf0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66            Open f
21d00 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
21d10 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68  data.db". Use th
21d20 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75  e special VFS "u
21d30 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20  nix-nolock"..** 
21d40 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
21d50 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f  ta.db?mode=reado
21d60 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  nly <td> .**    
21d70 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20        An error. 
21d80 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f  "readonly" is no
21d90 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e  t a valid option
21da0 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20   for the "mode" 
21db0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f  parameter..** </
21dc0 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52  table>.**.** ^UR
21dd0 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  I hexadecimal es
21de0 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 28  cape sequences (
21df0 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 74  %HH) are support
21e00 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 61  ed within the pa
21e10 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20  th and.** query 
21e20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20  components of a 
21e30 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d  URI. A hexadecim
21e40 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
21e50 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61  ce consists of a
21e60 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e  .** percent sign
21e70 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65   - "%" - followe
21e80 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f  d by exactly two
21e90 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67   hexadecimal dig
21ea0 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69  its .** specifyi
21eb0 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75  ng an octet valu
21ec0 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70  e. ^Before the p
21ed0 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d  ath or query com
21ee0 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20  ponents of a.** 
21ef0 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65  URI filename are
21f00 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68   interpreted, th
21f10 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75  ey are encoded u
21f20 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61  sing UTF-8 and a
21f30 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d  ll .** hexadecim
21f40 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
21f50 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 20  ces replaced by 
21f60 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f  a single byte co
21f70 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20  ntaining the.** 
21f80 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63  corresponding oc
21f90 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f  tet. If this pro
21fa0 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 61  cess generates a
21fb0 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20  n invalid UTF-8 
21fc0 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65  encoding,.** the
21fd0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
21fe0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62  efined..**.** <b
21ff0 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
22000 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
22010 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66   encoding used f
22020 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  or the filename 
22030 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73  argument.** of s
22040 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
22050 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
22060 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d  2() must be UTF-
22070 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a  8, not whatever.
22080 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63  ** codepage is c
22090 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
220a0 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e  .  Filenames con
220b0 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74  taining internat
220c0 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74  ional.** charact
220d0 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ers must be conv
220e0 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70  erted to UTF-8 p
220f0 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20  rior to passing 
22100 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  them into.** sql
22110 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
22120 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
22130 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20  ..**.** <b>Note 
22140 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69  to Windows Runti
22150 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54  me users:</b>  T
22160 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72  he temporary dir
22170 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73  ectory must be s
22180 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63  et.** prior to c
22190 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f  alling sqlite3_o
221a0 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
221b0 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68  _open_v2().  Oth
221c0 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a  erwise, various.
221d0 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74  ** features that
221e0 20 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65   require the use
221f0 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69   of temporary fi
22200 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a  les may fail..**
22210 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
22220 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65  qlite3_temp_dire
22230 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71  ctory].*/.int sq
22240 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f  lite3_open(.  co
22250 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
22260 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
22270 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
22280 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
22290 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
222a0 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
222b0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
222c0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nt sqlite3_open1
222d0 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  6(.  const void 
222e0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
222f0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
22300 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20  e (UTF-16) */.  
22310 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
22320 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
22330 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
22340 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
22350 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f  e3_open_v2(.  co
22360 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
22370 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
22380 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
22390 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
223a0 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20  **ppDb,         
223b0 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
223c0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e  b handle */.  in
223d0 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20  t flags,        
223e0 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a        /* Flags *
223f0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
22400 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e  zVfs        /* N
22410 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c  ame of VFS modul
22420 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a  e to use */.);..
22430 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
22440 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f  Obtain Values Fo
22450 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 72 73  r URI Parameters
22460 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65  .**.** These are
22470 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65   utility routine
22480 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53  s, useful to VFS
22490 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
224a0 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20  , that check.** 
224b0 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 74 61  to see if a data
224c0 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 61 20  base file was a 
224d0 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  URI that contain
224e0 65 64 20 61 20 73 70 65 63 69 66 69 63 20 71 75  ed a specific qu
224f0 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65  ery .** paramete
22500 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74  r, and if so obt
22510 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f  ains the value o
22520 66 20 74 68 61 74 20 71 75 65 72 79 20 70 61 72  f that query par
22530 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  ameter..**.** If
22540 20 46 20 69 73 20 74 68 65 20 64 61 74 61 62 61   F is the databa
22550 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e  se filename poin
22560 74 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ter passed into 
22570 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68  the xOpen() meth
22580 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20  od of .** a VFS 
22590 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
225a0 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61  hen the flags pa
225b0 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
225c0 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a  () has one or .*
225d0 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53  * more of the [S
225e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
225f0 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
22600 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65  MAIN_DB] bits se
22610 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68  t and.** P is th
22620 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75  e name of the qu
22630 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74  ery parameter, t
22640 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  hen.** sqlite3_u
22650 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
22660 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61  ) returns the va
22670 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20  lue of the P.** 
22680 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 20  parameter if it 
22690 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c  exists or a NULL
226a0 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f   pointer if P do
226b0 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73  es not appear as
226c0 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72   a .** query par
226d0 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66  ameter on F.  If
226e0 20 50 20 69 73 20 61 20 71 75 65 72 79 20 70 61   P is a query pa
226f0 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20  rameter of F.** 
22700 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20  has no explicit 
22710 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69  value, then sqli
22720 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
22730 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a  r(F,P) returns.*
22740 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
22750 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a  n empty string..
22760 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
22770 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
22780 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73  P,B) routine ass
22790 75 6d 65 73 20 74 68 61 74 20 50 20 69 73 20 61  umes that P is a
227a0 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61   boolean.** para
227b0 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
227c0 73 20 74 72 75 65 20 28 31 29 20 6f 72 20 66 61  s true (1) or fa
227d0 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e  lse (0) accordin
227e0 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a  g to the value.*
227f0 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c  * of P.  The sql
22800 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
22810 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20  (F,P,B) routine 
22820 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
22830 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65   if the.** value
22840 20 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d 65   of query parame
22850 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20  ter P is one of 
22860 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f  "yes", "true", o
22870 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a  r "on" in any.**
22880 20 63 61 73 65 20 6f 72 20 69 66 20 74 68 65 20   case or if the 
22890 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74  value begins wit
228a0 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d  h a non-zero num
228b0 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71  ber.  The .** sq
228c0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
228d0 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
228e0 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  s returns false 
228f0 28 30 29 20 69 66 20 74 68 65 20 76 61 6c 75 65  (0) if the value
22900 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72   of.** query par
22910 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20  ameter P is one 
22920 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22  of "no", "false"
22930 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e  , or "off" in an
22940 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20  y case or.** if 
22950 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73  the value begins
22960 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20   with a numeric 
22970 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e  zero.  If P is n
22980 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61  ot a query.** pa
22990 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20  rameter on F or 
229a0 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  if the value of 
229b0 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61  P is does not ma
229c0 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a  tch any of the.*
229d0 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71  * above, then sq
229e0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
229f0 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73  n(F,P,B) returns
22a00 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54   (B!=0)..**.** T
22a10 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69  he sqlite3_uri_i
22a20 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74  nt64(F,P,D) rout
22a30 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ine converts the
22a40 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f   value of P into
22a50 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67   a.** 64-bit sig
22a60 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20  ned integer and 
22a70 72 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74  returns that int
22a80 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20  eger, or D if P 
22a90 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73  does not.** exis
22aa0 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75 65  t.  If the value
22ab0 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69   of P is somethi
22ac0 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e  ng other than an
22ad0 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a   integer, then.*
22ae0 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e  * zero is return
22af0 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20  ed..** .** If F 
22b00 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
22b10 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  r, then sqlite3_
22b20 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c  uri_parameter(F,
22b30 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20  P) returns NULL 
22b40 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  and.** sqlite3_u
22b50 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
22b60 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66  ) returns B.  If
22b70 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c   F is not a NULL
22b80 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20   pointer and.** 
22b90 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
22ba0 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  e file pathname 
22bb0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c  pointer that SQL
22bc0 69 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ite passed into 
22bd0 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53  the xOpen.** VFS
22be0 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68   method, then th
22bf0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
22c00 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e  is routine is un
22c10 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
22c20 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61  ably.** undesira
22c30 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ble..*/.const ch
22c40 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f  ar *sqlite3_uri_
22c50 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20  parameter(const 
22c60 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c  char *zFilename,
22c70 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
22c80 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ram);.int sqlite
22c90 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f  3_uri_boolean(co
22ca0 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c  nst char *zFile,
22cb0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
22cc0 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c  ram, int bDefaul
22cd0 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  t);.sqlite3_int6
22ce0 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e  4 sqlite3_uri_in
22cf0 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t64(const char*,
22d00 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71   const char*, sq
22d10 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a  lite3_int64);...
22d20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
22d30 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20  Error Codes And 
22d40 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e  Messages.**.** ^
22d50 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63  The sqlite3_errc
22d60 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ode() interface 
22d70 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
22d80 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  ric [result code
22d90 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
22da0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66  d result code] f
22db0 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  or the most rece
22dc0 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65  nt failed sqlite
22dd0 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20  3_* API call.** 
22de0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
22df0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
22e00 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72  ection]. If a pr
22e10 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69  ior API call fai
22e20 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d  led.** but the m
22e30 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63  ost recent API c
22e40 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74  all succeeded, t
22e50 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
22e60 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  from.** sqlite3_
22e70 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64  errcode() is und
22e80 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71  efined.  ^The sq
22e90 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
22ea0 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65  rrcode().** inte
22eb0 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d  rface is the sam
22ec0 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  e except that it
22ed0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
22ee0 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  the .** [extende
22ef0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65  d result code] e
22f00 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65  ven when extende
22f10 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
22f20 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a  re.** disabled..
22f30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
22f40 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20  e3_errmsg() and 
22f50 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
22f60 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73  () return Englis
22f70 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65  h-language.** te
22f80 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65  xt that describe
22f90 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20  s the error, as 
22fa0 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
22fb0 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76  UTF-16 respectiv
22fc0 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  ely..** ^(Memory
22fd0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
22fe0 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
22ff0 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
23000 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20  ernally..** The 
23010 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
23020 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72   not need to wor
23030 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67  ry about freeing
23040 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20   the result..** 
23050 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72  However, the err
23060 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20  or string might 
23070 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f  be overwritten o
23080 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79  r deallocated by
23090 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63  .** subsequent c
230a0 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51  alls to other SQ
230b0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66  Lite interface f
230c0 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a  unctions.)^.**.*
230d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
230e0 72 72 73 74 72 28 29 20 69 6e 74 65 72 66 61 63  rrstr() interfac
230f0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e  e returns the En
23100 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74  glish-language t
23110 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63  ext.** that desc
23120 72 69 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c  ribes the [resul
23130 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d  t code], as UTF-
23140 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  8..** ^(Memory t
23150 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
23160 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
23170 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
23180 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73  nally.** and mus
23190 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62  t not be freed b
231a0 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
231b0 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  n)^..**.** When 
231c0 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
231d0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
231e0 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69  is in use, it mi
231f0 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61  ght be the.** ca
23200 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64  se that a second
23210 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e   error occurs on
23220 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
23230 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ad in between.**
23240 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65   the time of the
23250 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64   first error and
23260 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65   the call to the
23270 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  se interfaces..*
23280 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70  * When that happ
23290 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20  ens, the second 
232a0 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65  error will be re
232b0 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65  ported since the
232c0 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  se.** interfaces
232d0 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74   always report t
232e0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72  he most recent r
232f0 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64  esult.  To avoid
23300 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74  .** this, each t
23310 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e  hread can obtain
23320 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f   exclusive use o
23330 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
23340 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a  connection] D.**
23350 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71   by invoking [sq
23360 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
23370 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  r]([sqlite3_db_m
23380 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65  utex](D)) before
23390 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f   beginning.** to
233a0 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b   use D and invok
233b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
233c0 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74  ex_leave]([sqlit
233d0 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
233e0 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61   after.** all ca
233f0 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72  lls to the inter
23400 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72  faces listed her
23410 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e  e are completed.
23420 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74  .**.** If an int
23430 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74  erface fails wit
23440 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c  h SQLITE_MISUSE,
23450 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
23460 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73  interface.** was
23470 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65   invoked incorre
23480 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c  ctly by the appl
23490 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61  ication.  In tha
234a0 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65  t case, the.** e
234b0 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65  rror code and me
234c0 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79  ssage may or may
234d0 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a   not be set..*/.
234e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63  int sqlite3_errc
234f0 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
23500 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  ;.int sqlite3_ex
23510 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73  tended_errcode(s
23520 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e  qlite3 *db);.con
23530 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
23540 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a  _errmsg(sqlite3*
23550 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
23560 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
23570 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74  sqlite3*);.const
23580 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
23590 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  rrstr(int);../*.
235a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
235b0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
235c0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
235d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
235e0 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74  nt} {prepared st
235f0 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20  atements}.**.** 
23600 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
23610 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65  his object repre
23620 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53  sents a single S
23630 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  QL statement..**
23640 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
23650 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20  variously known 
23660 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73  as a "prepared s
23670 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a  tatement" or a.*
23680 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20  * "compiled SQL 
23690 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69  statement" or si
236a0 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65  mply as a "state
236b0 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment"..**.** The
236c0 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65   life of a state
236d0 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73  ment object goes
236e0 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20   something like 
236f0 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  this:.**.** <ol>
23700 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20  .** <li> Create 
23710 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
23720 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
23730 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c  e_v2()] or a rel
23740 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e  ated.**      fun
23750 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42  ction..** <li> B
23760 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68  ind values to [h
23770 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20  ost parameters] 
23780 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
23790 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20  3_bind_*().**   
237a0 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a     interfaces..*
237b0 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53  * <li> Run the S
237c0 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  QL by calling [s
237d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
237e0 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
237f0 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20  ..** <li> Reset 
23800 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73  the statement us
23810 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
23820 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61  et()] then go ba
23830 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74  ck.**      to st
23840 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a  ep 2.  Do this z
23850 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  ero or more time
23860 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72  s..** <li> Destr
23870 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  oy the object us
23880 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
23890 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f  alize()]..** </o
238a0 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74  l>.**.** Refer t
238b0 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  o documentation 
238c0 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65  on individual me
238d0 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20  thods above for 
238e0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
238f0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  formation..*/.ty
23900 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
23910 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65  ite3_stmt sqlite
23920 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  3_stmt;../*.** C
23930 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d  API3REF: Run-tim
23940 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e  e Limits.**.** ^
23950 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  (This interface 
23960 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20  allows the size 
23970 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74  of various const
23980 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69  ructs to be limi
23990 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e  ted.** on a conn
239a0 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63  ection by connec
239b0 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65  tion basis.  The
239c0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
239d0 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61   is the.** [data
239e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
239f0 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20   whose limit is 
23a00 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65  to be set or que
23a10 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ried.  The.** se
23a20 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
23a30 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69  s one of the [li
23a40 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20  mit categories] 
23a50 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a  that define a.**
23a60 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72   class of constr
23a70 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20  ucts to be size 
23a80 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68  limited.  The th
23a90 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
23aa0 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69   the.** new limi
23ab0 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74  t for that const
23ac0 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49  ruct.)^.**.** ^I
23ad0 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20  f the new limit 
23ae0 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75  is a negative nu
23af0 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20  mber, the limit 
23b00 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  is unchanged..**
23b10 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69   ^(For each limi
23b20 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54  t category SQLIT
23b30 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c  E_LIMIT_<i>NAME<
23b40 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a  /i> there is a .
23b50 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72  ** [limits | har
23b60 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a  d upper bound].*
23b70 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  * set at compile
23b80 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65  -time by a C pre
23b90 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
23ba0 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74  called.** [limit
23bb0 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c  s | SQLITE_MAX_<
23bc0 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20  i>NAME</i>]..** 
23bd0 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69  (The "_LIMIT_" i
23be0 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68  n the name is ch
23bf0 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22  anged to "_MAX_"
23c00 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74  .))^.** ^Attempt
23c10 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20  s to increase a 
23c20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20  limit above its 
23c30 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
23c40 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79   are.** silently
23c50 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68   truncated to th
23c60 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  e hard upper bou
23c70 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72  nd..**.** ^Regar
23c80 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
23c90 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69   or not the limi
23ca0 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74  t was changed, t
23cb0 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
23cc0 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61  limit()] interfa
23cd0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70  ce returns the p
23ce0 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68  rior value of th
23cf0 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e  e limit..** ^Hen
23d00 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ce, to find the 
23d10 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
23d20 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74   a limit without
23d30 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a   changing it,.**
23d40 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74   simply invoke t
23d50 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69  his interface wi
23d60 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72  th the third par
23d70 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31  ameter set to -1
23d80 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65  ..**.** Run-time
23d90 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65   limits are inte
23da0 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
23db0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
23dc0 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68  t manage.** both
23dd0 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72   their own inter
23de0 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64  nal database and
23df0 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20   also databases 
23e00 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c  that are control
23e10 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73  led.** by untrus
23e20 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75  ted external sou
23e30 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c  rces.  An exampl
23e40 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69  e application mi
23e50 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20  ght be a.** web 
23e60 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73  browser that has
23e70 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73   its own databas
23e80 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68  es for storing h
23e90 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65  istory and.** se
23ea0 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73  parate databases
23eb0 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a   controlled by J
23ec0 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63  avaScript applic
23ed0 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65  ations downloade
23ee0 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74  d.** off the Int
23ef0 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65  ernet.  The inte
23f00 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63  rnal databases c
23f10 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a  an be given the.
23f20 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c  ** large, defaul
23f30 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62  t limits.  Datab
23f40 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20  ases managed by 
23f50 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
23f60 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e   can.** be given
23f70 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69   much smaller li
23f80 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f  mits designed to
23f90 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61   prevent a denia
23fa0 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20  l of service.** 
23fb0 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70  attack.  Develop
23fc0 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77  ers might also w
23fd0 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b  ant to use the [
23fe0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
23ff0 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74  orizer()].** int
24000 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65  erface to furthe
24010 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73  r control untrus
24020 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69  ted SQL.  The si
24030 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ze of the databa
24040 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  se.** created by
24050 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63   an untrusted sc
24060 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74  ript can be cont
24070 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a  ained using the.
24080 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  ** [max_page_cou
24090 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a  nt] [PRAGMA]..**
240a0 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65  .** New run-time
240b0 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65   limit categorie
240c0 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
240d0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
240e0 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
240f0 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a  3_limit(sqlite3*
24100 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65  , int id, int ne
24110 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  wVal);../*.** CA
24120 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
24130 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65   Limit Categorie
24140 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
24150 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20  limit category} 
24160 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  {*limit categori
24170 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es}.**.** These 
24180 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
24190 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d   various perform
241a0 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74  ance limits.** t
241b0 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72  hat can be lower
241c0 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75  ed at run-time u
241d0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
241e0 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  mit()]..** The s
241f0 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d  ynopsis of the m
24200 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76  eanings of the v
24210 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73  arious limits is
24220 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a   shown below..**
24230 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   Additional info
24240 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c  rmation is avail
24250 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20  able at [limits 
24260 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69  | Limits in SQLi
24270 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  te]..**.** <dl>.
24280 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
24290 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74  T_LENGTH]] ^(<dt
242a0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  >SQLITE_LIMIT_LE
242b0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
242c0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a  >The maximum siz
242d0 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20  e of any string 
242e0 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65  or BLOB or table
242f0 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c   row, in bytes.<
24300 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
24310 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
24320 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
24330 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
24340 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
24350 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
24360 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73  ngth of an SQL s
24370 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74  tatement, in byt
24380 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  es.</dd>)^.**.**
24390 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
243a0 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53  COLUMN]] ^(<dt>S
243b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
243c0 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  MN</dt>.** <dd>T
243d0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
243e0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
243f0 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69  a table definiti
24400 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20  on or in the.** 
24410 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
24420 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20  [SELECT] or the 
24430 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
24440 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20  f columns in an 
24450 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61  index.** or in a
24460 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52  n ORDER BY or GR
24470 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f  OUP BY clause.</
24480 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
24490 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
244a0 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
244b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
244c0 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
244d0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
244e0 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65  pth of the parse
244f0 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70   tree on any exp
24500 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  ression.</dd>)^.
24510 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
24520 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
24530 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LECT]] ^(<dt>SQL
24540 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
24550 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a  ND_SELECT</dt>.*
24560 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
24570 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  m number of term
24580 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20  s in a compound 
24590 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
245a0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
245b0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  [SQLITE_LIMIT_VD
245c0 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51  BE_OP]] ^(<dt>SQ
245d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
245e0 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OP</dt>.** <dd>T
245f0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
24600 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e  r of instruction
24610 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d  s in a virtual m
24620 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a  achine program.*
24630 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  * used to implem
24640 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ent an SQL state
24650 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69  ment.  This limi
24660 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  t is not current
24670 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20  ly.** enforced, 
24680 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68  though that migh
24690 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f  t be added in so
246a0 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  me future releas
246b0 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c  e of.** SQLite.<
246c0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
246d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
246e0 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74  TION_ARG]] ^(<dt
246f0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  >SQLITE_LIMIT_FU
24700 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a  NCTION_ARG</dt>.
24710 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
24720 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  um number of arg
24730 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63  uments on a func
24740 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  tion.</dd>)^.**.
24750 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
24760 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c  T_ATTACHED]] ^(<
24770 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
24780 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a  ATTACHED</dt>.**
24790 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
247a0 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41   number of [ATTA
247b0 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61  CH | attached da
247c0 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e  tabases].)^</dd>
247d0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
247e0 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
247f0 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e  RN_LENGTH]].** ^
24800 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
24810 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
24820 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
24830 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
24840 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74  ngth of the patt
24850 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ern argument to 
24860 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a  the [LIKE] or.**
24870 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
24880 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
24890 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
248a0 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d  ARIABLE_NUMBER]]
248b0 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
248c0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
248d0 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  NUMBER</dt>.** <
248e0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69  dd>The maximum i
248f0 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61  ndex number of a
24900 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69  ny [parameter] i
24910 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
24920 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  nt.)^.**.** [[SQ
24930 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
24940 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74  ER_DEPTH]] ^(<dt
24950 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  >SQLITE_LIMIT_TR
24960 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e  IGGER_DEPTH</dt>
24970 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
24980 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63  mum depth of rec
24990 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67  ursion for trigg
249a0 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  ers.</dd>)^.** <
249b0 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
249c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
249d0 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
249e0 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
249f0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51   SQLITE_LIMIT_SQ
24a00 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  L_LENGTH        
24a10 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
24a20 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
24a30 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20  OLUMN           
24a40 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
24a50 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
24a60 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20  EXPR_DEPTH      
24a70 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66            3.#def
24a80 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
24a90 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
24aa0 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
24ab0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
24ac0 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20  T_VDBE_OP       
24ad0 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
24ae0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
24af0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20  IT_FUNCTION_ARG 
24b00 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
24b10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
24b20 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20  MIT_ATTACHED    
24b30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a                7.
24b40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
24b50 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
24b60 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38  N_LENGTH       8
24b70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24b80 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
24b90 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20  UMBER           
24ba0 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
24bb0 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
24bc0 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
24bd0 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  10../*.** CAPI3R
24be0 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e  EF: Compiling An
24bf0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
24c00 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
24c10 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69   statement compi
24c20 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78  ler}.**.** To ex
24c30 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65  ecute an SQL que
24c40 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73  ry, it must firs
24c50 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e  t be compiled in
24c60 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a  to a byte-code.*
24c70 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20  * program using 
24c80 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  one of these rou
24c90 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tines..**.** The
24ca0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c   first argument,
24cb0 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74   "db", is a [dat
24cc0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24cd0 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  ] obtained from 
24ce0 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65  a.** prior succe
24cf0 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
24d00 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
24d10 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
24d20 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
24d30 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54  e3_open16()].  T
24d40 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
24d50 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  ection must not 
24d60 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64  have been closed
24d70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
24d80 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53  nd argument, "zS
24d90 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74  ql", is the stat
24da0 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
24db0 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a  iled, encoded.**
24dc0 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
24dd0 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65   or UTF-16.  The
24de0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
24df0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
24e00 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69  repare_v2().** i
24e10 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54  nterfaces use UT
24e20 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  F-8, and sqlite3
24e30 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64  _prepare16() and
24e40 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
24e50 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55  16_v2().** use U
24e60 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  TF-16..**.** ^If
24e70 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d   the nByte argum
24e80 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ent is less than
24e90 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c   zero, then zSql
24ea0 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74   is read up to t
24eb0 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f  he.** first zero
24ec0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66   terminator. ^If
24ed0 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65   nByte is non-ne
24ee0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20  gative, then it 
24ef0 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a  is the maximum.*
24f00 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74  * number of  byt
24f10 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71  es read from zSq
24f20 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20  l.  ^When nByte 
24f30 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
24f40 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72   the.** zSql str
24f50 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68  ing ends at eith
24f60 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30  er the first '\0
24f70 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20  00' or '\u0000' 
24f80 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20  character or.** 
24f90 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74  the nByte-th byt
24fa0 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  e, whichever com
24fb0 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65  es first. If the
24fc0 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a   caller knows.**
24fd0 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69   that the suppli
24fe0 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c  ed string is nul
24ff0 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65  -terminated, the
25000 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61  n there is a sma
25010 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63  ll.** performanc
25020 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62  e advantage to b
25030 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73  e gained by pass
25040 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72  ing an nByte par
25050 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69  ameter that.** i
25060 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e  s equal to the n
25070 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
25080 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
25090 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c  ng <i>including<
250a0 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74  /i>.** the nul-t
250b0 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20  erminator bytes 
250c0 61 73 20 74 68 69 73 20 73 61 76 65 73 20 53 51  as this saves SQ
250d0 4c 69 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67  Lite from having
250e0 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f   to.** make a co
250f0 70 79 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20  py of the input 
25100 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  string..**.** ^I
25110 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20  f pzTail is not 
25120 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69  NULL then *pzTai
25130 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
25140 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  nt to the first 
25150 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65  byte.** past the
25160 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73   end of the firs
25170 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
25180 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20  in zSql.  These 
25190 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a  routines only.**
251a0 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72   compile the fir
251b0 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  st statement in 
251c0 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c  zSql, so *pzTail
251d0 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
251e0 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d  g to.** what rem
251f0 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e  ains uncompiled.
25200 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20  .**.** ^*ppStmt 
25210 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
25220 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b   to a compiled [
25230 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25240 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a  nt] that can be.
25250 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e  ** executed usin
25260 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
25270 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69  )].  ^If there i
25280 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53  s an error, *ppS
25290 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f  tmt is set.** to
252a0 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20   NULL.  ^If the 
252b0 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61  input text conta
252c0 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74  ins no SQL (if t
252d0 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65  he input is an e
252e0 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  mpty.** string o
252f0 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
25300 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
25310 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65   to NULL..** The
25320 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75   calling procedu
25330 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  re is responsibl
25340 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74  e for deleting t
25350 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53  he compiled.** S
25360 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  QL statement usi
25370 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
25380 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74  lize()] after it
25390 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
253a0 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74  th it..** ppStmt
253b0 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c   may not be NULL
253c0 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63  ..**.** ^On succ
253d0 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ess, the sqlite3
253e0 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c  _prepare() famil
253f0 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65  y of routines re
25400 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
25410 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61  ;.** otherwise a
25420 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
25430 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
25440 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
25450 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73  epare_v2() and s
25460 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
25470 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73  _v2() interfaces
25480 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e   are.** recommen
25490 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20  ded for all new 
254a0 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77  programs. The tw
254b0 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63  o older interfac
254c0 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a  es are retained.
254d0 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ** for backwards
254e0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20   compatibility, 
254f0 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73  but their use is
25500 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a   discouraged..**
25510 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
25520 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72  terfaces, the pr
25530 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25540 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75  .** that is retu
25550 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  rned (the [sqlit
25560 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29  e3_stmt] object)
25570 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79   contains a copy
25580 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69   of the.** origi
25590 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68  nal SQL text. Th
255a0 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73  is causes the [s
255b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69  qlite3_step()] i
255c0 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62  nterface to.** b
255d0 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c  ehave differentl
255e0 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a  y in three ways:
255f0 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
25600 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  li>.** ^If the d
25610 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
25620 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20  hanges, instead 
25630 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  of returning [SQ
25640 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20  LITE_SCHEMA] as 
25650 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  it.** always use
25660 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65  d to do, [sqlite
25670 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61  3_step()] will a
25680 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
25690 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a  ompile the SQL.*
256a0 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  * statement and 
256b0 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67  try to run it ag
256c0 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20  ain. As many as 
256d0 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45  [SQLITE_MAX_SCHE
256e0 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74  MA_RETRY].** ret
256f0 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20  ries will occur 
25700 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73  before sqlite3_s
25710 74 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61  tep() gives up a
25720 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72  nd returns an er
25730 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ror..** </li>.**
25740 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65  .** <li>.** ^Whe
25750 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  n an error occur
25760 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  s, [sqlite3_step
25770 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
25780 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69  one of the detai
25790 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f  led.** [error co
257a0 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  des] or [extende
257b0 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20  d error codes]. 
257c0 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68   ^The legacy beh
257d0 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a  avior was that.*
257e0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
257f0 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65  )] would only re
25800 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b  turn a generic [
25810 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65  SQLITE_ERROR] re
25820 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64  sult code.** and
25830 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
25840 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d   would have to m
25850 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c  ake a second cal
25860 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  l to [sqlite3_re
25870 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64  set()].** in ord
25880 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75  er to find the u
25890 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20  nderlying cause 
258a0 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20  of the problem. 
258b0 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72  With the "v2" pr
258c0 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61  epare.** interfa
258d0 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79  ces, the underly
258e0 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74  ing reason for t
258f0 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  he error is retu
25900 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
25910 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
25920 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
25930 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20   specific value 
25940 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65  bound to [parame
25950 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d  ter | host param
25960 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a  eter] in the .**
25970 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69   WHERE clause mi
25980 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
25990 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  e choice of quer
259a0 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61  y plan for a sta
259b0 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20  tement,.** then 
259c0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69  the statement wi
259d0 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
259e0 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20  lly recompiled, 
259f0 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20  as if there had 
25a00 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d  been .** a schem
25a10 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65  a change, on the
25a20 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33   first  [sqlite3
25a30 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f  _step()] call fo
25a40 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e  llowing any chan
25a50 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  ge.** to the [sq
25a60 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20  lite3_bind_text 
25a70 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74  | bindings] of t
25a80 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e  hat [parameter].
25a90 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66   .** ^The specif
25aa0 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52  ic value of WHER
25ab0 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65  E-clause [parame
25ac0 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75  ter] might influ
25ad0 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f  ence the .** cho
25ae0 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
25af0 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  n if the paramet
25b00 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68  er is the left-h
25b10 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c  and side of a [L
25b20 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42  IKE].** or [GLOB
25b30 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66  ] operator or if
25b40 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
25b50 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e  s compared to an
25b60 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a   indexed column.
25b70 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49  ** and the [SQLI
25b80 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d  TE_ENABLE_STAT3]
25b90 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
25ba0 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
25bb0 0a 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69  .** the .** </li
25bc0 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e  >.** </ol>.*/.in
25bd0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
25be0 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
25bf0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
25c00 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
25c10 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
25c20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
25c30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
25c40 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
25c50 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
25c60 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
25c70 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
25c80 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
25c90 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
25ca0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
25cb0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
25cc0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
25cd0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
25ce0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
25cf0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
25d00 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
25d10 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
25d20 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  pare_v2(.  sqlit
25d30 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
25d40 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
25d50 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
25d60 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
25d70 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
25d80 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
25d90 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
25da0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
25db0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
25dc0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
25dd0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
25de0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
25df0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
25e00 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
25e10 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
25e20 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
25e30 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
25e40 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
25e50 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
25e60 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20  e3_prepare16(.  
25e70 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
25e80 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
25e90 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
25ea0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
25eb0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
25ec0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
25ed0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
25ee0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
25ef0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
25f00 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
25f10 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
25f20 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
25f30 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
25f40 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
25f50 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
25f60 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
25f70 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
25f80 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
25f90 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
25fa0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
25fb0 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  16_v2(.  sqlite3
25fc0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
25fd0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
25fe0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
25ff0 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
26000 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
26010 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
26020 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
26030 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
26040 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
26050 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
26060 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
26070 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
26080 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
26090 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
260a0 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
260b0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
260c0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
260d0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
260e0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
260f0 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e  I3REF: Retrievin
26100 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a  g Statement SQL.
26110 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
26120 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
26130 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20  d to retrieve a 
26140 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68  saved copy of th
26150 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51  e original.** SQ
26160 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63  L text used to c
26170 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65  reate a [prepare
26180 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20  d statement] if 
26190 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77  that statement w
261a0 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75  as.** compiled u
261b0 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
261c0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
261d0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
261e0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
261f0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
26200 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74  qlite3_sql(sqlit
26210 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
26220 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
26230 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
26240 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
26250 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62  Writes The Datab
26260 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ase.**.** ^The s
26270 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
26280 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63  only(X) interfac
26290 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
262a0 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20  non-zero) if.** 
262b0 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
262c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
262d0 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20  ent] X makes no 
262e0 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74  direct changes t
262f0 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  o.** the content
26300 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
26310 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74   file..**.** Not
26320 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74  e that [applicat
26330 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
26340 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a  functions] or.**
26350 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73   [virtual tables
26360 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74  ] might change t
26370 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69  he database indi
26380 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65  rectly as a side
26390 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28   effect.  .** ^(
263a0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  For example, if 
263b0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  an application d
263c0 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f  efines a functio
263d0 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20  n "eval()" that 
263e0 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74  .** calls [sqlit
263f0 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e  e3_exec()], then
26400 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   the following S
26410 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75  QL statement wou
26420 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  ld.** change the
26430 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
26440 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65  hrough side-effe
26450 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  cts:.**.** <bloc
26460 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
26470 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27     SELECT eval('
26480 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29  DELETE FROM t1')
26490 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70   FROM t2;.** </p
264a0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
264b0 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75  .**.** But becau
264c0 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  se the [SELECT] 
264d0 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
264e0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ot change the da
264f0 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64  tabase file.** d
26500 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33  irectly, sqlite3
26510 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
26520 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74   would still ret
26530 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a  urn true.)^.**.*
26540 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63  * ^Transaction c
26550 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74  ontrol statement
26560 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e  s such as [BEGIN
26570 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f  ], [COMMIT], [RO
26580 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56  LLBACK],.** [SAV
26590 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45  EPOINT], and [RE
265a0 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c  LEASE] cause sql
265b0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
265c0 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
265d0 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68  rue,.** since th
265e0 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65  e statements the
265f0 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61  mselves do not a
26600 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74  ctually modify t
26610 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a  he database but.
26620 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63  ** rather they c
26630 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e  ontrol the timin
26640 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20  g of when other 
26650 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66  statements modif
26660 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61  y the .** databa
26670 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43  se.  ^The [ATTAC
26680 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20  H] and [DETACH] 
26690 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20  statements also 
266a0 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33  cause.** sqlite3
266b0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
266c0 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20   to return true 
266d0 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f  since, while tho
266e0 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  se statements.**
266f0 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66   change the conf
26700 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64  iguration of a d
26710 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
26720 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20  on, they do not 
26730 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73  make .** changes
26740 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   to the content 
26750 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
26760 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a  files on disk..*
26770 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
26780 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69  mt_readonly(sqli
26790 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
267a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
267b0 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
267c0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
267d0 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65  ment Has Been Re
267e0 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  set.**.** ^The s
267f0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
26800 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (S) interface re
26810 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
26820 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20  zero) if the.** 
26830 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26840 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20  ent] S has been 
26850 73 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74  stepped at least
26860 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20   once using .** 
26870 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
26880 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 20 72 75  ] but has not ru
26890 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  n to completion 
268a0 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a  and/or has not .
268b0 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73  ** been reset us
268c0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
268d0 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71  et(S)].  ^The sq
268e0 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
268f0 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  S).** interface 
26900 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66  returns false if
26910 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   S is a NULL poi
26920 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e  nter.  If S is n
26930 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  ot a .** NULL po
26940 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74  inter and is not
26950 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
26960 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20  valid [prepared 
26970 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
26980 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62  ject, then the b
26990 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
269a0 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
269b0 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  y undesirable..*
269c0 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
269d0 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
269e0 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b  in combination [
269f0 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
26a00 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74  t()].** to locat
26a10 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73  e all prepared s
26a20 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69  tatements associ
26a30 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61  ated with a data
26a40 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74  base .** connect
26a50 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20  ion that are in 
26a60 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65  need of being re
26a70 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62  set.  This can b
26a80 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65  e used,.** for e
26a90 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e  xample, in diagn
26aa0 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74  ostic routines t
26ab0 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65  o search for pre
26ac0 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d  pared .** statem
26ad0 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f  ents that are ho
26ae0 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74  lding a transact
26af0 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74  ion open..*/.int
26b00 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
26b10 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  sy(sqlite3_stmt*
26b20 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
26b30 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20  EF: Dynamically 
26b40 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65  Typed Value Obje
26b50 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
26b60 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  {protected sqlit
26b70 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f  e3_value} {unpro
26b80 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
26b90 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  alue}.**.** SQLi
26ba0 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69  te uses the sqli
26bb0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
26bc0 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c   to represent al
26bd0 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74  l values.** that
26be0 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69   can be stored i
26bf0 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
26c00 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20  le. SQLite uses 
26c10 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a  dynamic typing.*
26c20 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73  * for the values
26c30 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61   it stores.  ^Va
26c40 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73  lues stored in s
26c50 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
26c60 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69  ects.** can be i
26c70 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e  ntegers, floatin
26c80 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20  g point values, 
26c90 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20  strings, BLOBs, 
26ca0 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41  or NULL..**.** A
26cb0 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
26cc0 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69  object may be ei
26cd0 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22  ther "protected"
26ce0 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64   or "unprotected
26cf0 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72  "..** Some inter
26d00 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20  faces require a 
26d10 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
26d20 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20  3_value.  Other 
26d30 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69  interfaces.** wi
26d40 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72  ll accept either
26d50 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20   a protected or 
26d60 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
26d70 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
26d80 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65   Every interface
26d90 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71   that accepts sq
26da0 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75  lite3_value argu
26db0 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a  ments specifies.
26dc0 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** whether or no
26dd0 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20  t it requires a 
26de0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
26df0 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  3_value..**.** T
26e00 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63  he terms "protec
26e10 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74  ted" and "unprot
26e20 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20  ected" refer to 
26e30 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a  whether or not.*
26e40 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c  * a mutex is hel
26e50 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20  d.  An internal 
26e60 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
26e70 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a  r a protected.**
26e80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
26e90 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74  bject but no mut
26ea0 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
26eb0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  n unprotected.**
26ec0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
26ed0 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74  bject.  If SQLit
26ee0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f  e is compiled to
26ef0 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61   be single-threa
26f00 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51  ded.** (with [SQ
26f10 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
26f20 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c  0] and with [sql
26f30 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
26f40 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a  )] returning 0).
26f50 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20  ** or if SQLite 
26f60 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66  is run in one of
26f70 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d   reduced mutex m
26f80 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  odes .** [SQLITE
26f90 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
26fa0 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45  READ] or [SQLITE
26fb0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
26fc0 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  EAD].** then the
26fd0 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63  re is no distinc
26fe0 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
26ff0 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
27000 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
27010 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
27020 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20  and they can be 
27030 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65  used interchange
27040 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a  ably.  However,.
27050 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63  ** for maximum c
27060 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20  ode portability 
27070 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
27080 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
27090 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b  ons.** still mak
270a0 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
270b0 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
270c0 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
270d0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
270e0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65  alue objects eve
270f0 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63  n when not stric
27100 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  tly required..**
27110 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
27120 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74  _value objects t
27130 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61  hat are passed a
27140 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74  s parameters int
27150 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  o the.** impleme
27160 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c  ntation of [appl
27170 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
27180 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61  SQL functions] a
27190 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a  re protected..**
271a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
271b0 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  lue object retur
271c0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
271d0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
271e0 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65  )] is unprotecte
271f0 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65  d..** Unprotecte
27200 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
27210 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79  objects may only
27220 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a   be used with.**
27230 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
27240 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
27250 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
27260 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71  e()]..** The [sq
27270 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
27280 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65   | sqlite3_value
27290 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20  _type()] family 
272a0 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  of.** interfaces
272b0 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74   require protect
272c0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
272d0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70   objects..*/.typ
272e0 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20  edef struct Mem 
272f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a  sqlite3_value;..
27300 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27310 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  SQL Function Con
27320 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  text Object.**.*
27330 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e  * The context in
27340 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75   which an SQL fu
27350 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20  nction executes 
27360 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a  is stored in an.
27370 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ** sqlite3_conte
27380 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70  xt object.  ^A p
27390 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c  ointer to an sql
273a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
273b0 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ect.** is always
273c0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
273d0 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   to [application
273e0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
273f0 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20  ctions]..** The 
27400 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
27410 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
27420 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
27430 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a  will pass this.*
27440 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67  * pointer throug
27450 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20  h into calls to 
27460 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
27470 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65  int | sqlite3_re
27480 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  sult()],.** [sql
27490 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
274a0 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69  ontext()], [sqli
274b0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
274c0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ,.** [sqlite3_co
274d0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
274e0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  )], [sqlite3_get
274f0 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  _auxdata()],.** 
27500 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f  and/or [sqlite3_
27510 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a  set_auxdata()]..
27520 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
27530 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
27540 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
27550 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
27560 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75  EF: Binding Valu
27570 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53  es To Prepared S
27580 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59  tatements.** KEY
27590 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72  WORDS: {host par
275a0 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61  ameter} {host pa
275b0 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20  rameters} {host 
275c0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a  parameter name}.
275d0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
275e0 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51  L parameter} {SQ
275f0 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70  L parameters} {p
27600 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
27610 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65  }.**.** ^(In the
27620 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
27630 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ext input to [sq
27640 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
27650 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  ()] and its vari
27660 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c  ants,.** literal
27670 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65  s may be replace
27680 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65  d by a [paramete
27690 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20  r] that matches 
276a0 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67  one of following
276b0 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a  .** templates:.*
276c0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
276d0 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e  >  ?.** <li>  ?N
276e0 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56  NN.** <li>  :VVV
276f0 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a  .** <li>  @VVV.*
27700 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20  * <li>  $VVV.** 
27710 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  </ul>.**.** In t
27720 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f  he templates abo
27730 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e  ve, NNN represen
27740 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69  ts an integer li
27750 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56  teral,.** and VV
27760 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  V represents an 
27770 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65  alphanumeric ide
27780 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65  ntifier.)^  ^The
27790 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65   values of these
277a0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28  .** parameters (
277b0 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73  also called "hos
277c0 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
277d0 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d  s" or "SQL param
277e0 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62  eters").** can b
277f0 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20  e set using the 
27800 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
27810 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65   routines define
27820 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  d here..**.** ^T
27830 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
27840 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
27850 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
27860 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20  es is always.** 
27870 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
27880 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
27890 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
278a0 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
278b0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
278c0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a  r its variants..
278d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
278e0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
278f0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53  e index of the S
27900 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  QL parameter to 
27910 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20  be set..** ^The 
27920 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72  leftmost SQL par
27930 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
27940 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e  dex of 1.  ^When
27950 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a   the same named.
27960 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ** SQL parameter
27970 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68   is used more th
27980 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20  an once, second 
27990 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  and subsequent.*
279a0 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61  * occurrences ha
279b0 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65  ve the same inde
279c0 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f  x as the first o
279d0 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54  ccurrence..** ^T
279e0 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d  he index for nam
279f0 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61  ed parameters ca
27a00 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75  n be looked up u
27a10 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
27a20 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
27a30 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49  ter_index()] API
27a40 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54   if desired.  ^T
27a50 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20  he index.** for 
27a60 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72  "?NNN" parameter
27a70 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  s is the value o
27a80 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e  f NNN..** ^The N
27a90 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65  NN value must be
27aa0 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74   between 1 and t
27ab0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  he [sqlite3_limi
27ac0 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65  t()].** paramete
27ad0 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  r [SQLITE_LIMIT_
27ae0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
27af0 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a   (default value:
27b00 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   999)..**.** ^Th
27b10 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
27b20 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f   is the value to
27b30 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72   bind to the par
27b40 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  ameter..** ^If t
27b50 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
27b60 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
27b70 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  nd_text() or sql
27b80 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
27b90 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
27ba0 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20  _bind_blob() is 
27bb0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
27bc0 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70  hen the fourth p
27bd0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69  arameter.** is i
27be0 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65  gnored and the e
27bf0 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 65  nd result is the
27c00 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33   same as sqlite3
27c10 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a  _bind_null()..**
27c20 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72  .** ^(In those r
27c30 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76  outines that hav
27c40 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d  e a fourth argum
27c50 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69  ent, its value i
27c60 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
27c70 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
27c80 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62  parameter.  To b
27c90 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c  e clear: the val
27ca0 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
27cb0 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c  ber of <u>bytes<
27cc0 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65  /u> in the value
27cd0 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
27ce0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29   of characters.)
27cf0 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75  ^.** ^If the fou
27d00 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
27d10 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
27d20 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
27d30 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a  bind_text16().**
27d40 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
27d50 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  en the length of
27d60 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a   the string is.*
27d70 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
27d80 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20  bytes up to the 
27d90 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
27da0 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65  nator..** If the
27db0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
27dc0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
27dd0 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61  d_blob() is nega
27de0 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  tive, then.** th
27df0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
27e00 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61  defined..** If a
27e10 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f   non-negative fo
27e20 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
27e30 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71  s provided to sq
27e40 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
27e50 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
27e60 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 74 68  bind_text16() th
27e70 65 6e 20 74 68 61 74 20 70 61 72 61 6d 65 74 65  en that paramete
27e80 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79  r must be the by
27e90 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65  te offset.** whe
27ea0 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69  re the NUL termi
27eb0 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75  nator would occu
27ec0 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73  r assuming the s
27ed0 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a  tring were NUL.*
27ee0 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49  * terminated.  I
27ef0 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63  f any NUL charac
27f00 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79  ters occur at by
27f10 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20  te offsets less 
27f20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c  than .** the val
27f30 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68  ue of the fourth
27f40 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20   parameter then 
27f50 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
27f60 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a  ring value will.
27f70 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64  ** contain embed
27f80 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72  ded NULs.  The r
27f90 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73  esult of express
27fa0 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73  ions involving s
27fb0 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65  trings.** with e
27fc0 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20  mbedded NULs is 
27fd0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
27fe0 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
27ff0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
28000 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  bind_blob(), sql
28010 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
28020 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  , and.** sqlite3
28030 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69  _bind_text16() i
28040 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75  s a destructor u
28050 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  sed to dispose o
28060 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a  f the BLOB or.**
28070 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51   string after SQ
28080 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65  Lite has finishe
28090 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65  d with it.  ^The
280a0 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63   destructor is c
280b0 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70  alled.** to disp
280c0 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
280d0 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69  or string even i
280e0 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71  f the call to sq
280f0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
28100 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69  ),.** sqlite3_bi
28110 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72 20 73 71  nd_text(), or sq
28120 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
28130 36 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20  6() fails.  .** 
28140 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
28150 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65  gument is.** the
28160 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b   special value [
28170 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20  SQLITE_STATIC], 
28180 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75  then SQLite assu
28190 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
281a0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69  information is i
281b0 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61  n static, unmana
281c0 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ged space and do
281d0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
281e0 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  e freed..** ^If 
281f0 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
28200 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65  nt has the value
28210 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
28220 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  NT], then.** SQL
28230 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77  ite makes its ow
28240 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
28250 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64  f the data immed
28260 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a  iately, before.*
28270 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * the sqlite3_bi
28280 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72  nd_*() routine r
28290 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
282a0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
282b0 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69  zeroblob() routi
282c0 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20  ne binds a BLOB 
282d0 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74  of length N that
282e0 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69  .** is filled wi
282f0 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a  th zeroes.  ^A z
28300 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66  eroblob uses a f
28310 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d  ixed amount of m
28320 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61  emory.** (just a
28330 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c  n integer to hol
28340 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c  d its size) whil
28350 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72  e it is being pr
28360 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f  ocessed..** Zero
28370 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64  blobs are intend
28380 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70  ed to serve as p
28390 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
283a0 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63  BLOBs whose.** c
283b0 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20  ontent is later 
283c0 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a  written using.**
283d0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
283e0 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61  pen | incrementa
283f0 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74  l BLOB I/O] rout
28400 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61  ines..** ^A nega
28410 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74  tive value for t
28420 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75  he zeroblob resu
28430 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65  lts in a zero-le
28440 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a  ngth BLOB..**.**
28450 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20   ^If any of the 
28460 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
28470 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
28480 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
28490 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20   pointer.** for 
284a0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
284b0 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68  atement] or with
284c0 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
284d0 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a  ement for which.
284e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
284f0 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c  ()] has been cal
28500 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c  led more recentl
28510 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f  y than [sqlite3_
28520 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65  reset()],.** the
28530 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20  n the call will 
28540 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d  return [SQLITE_M
28550 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20  ISUSE].  If any 
28560 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a  sqlite3_bind_().
28570 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61  ** routine is pa
28580 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64  ssed a [prepared
28590 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
285a0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
285b0 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75  zed, the.** resu
285c0 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  lt is undefined 
285d0 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72  and probably har
285e0 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e  mful..**.** ^Bin
285f0 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c  dings are not cl
28600 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71  eared by the [sq
28610 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72  lite3_reset()] r
28620 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f  outine..** ^Unbo
28630 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61  und parameters a
28640 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
28650 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s NULL..**.** ^T
28660 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
28670 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  * routines retur
28680 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
28690 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a   success or an.*
286a0 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  * [error code] i
286b0 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20  f anything goes 
286c0 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49  wrong..** ^[SQLI
286d0 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74  TE_RANGE] is ret
286e0 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72  urned if the par
286f0 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20  ameter.** index 
28700 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e  is out of range.
28710 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d    ^[SQLITE_NOMEM
28720 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
28730 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e   malloc() fails.
28740 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
28750 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
28760 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
28770 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
28780 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
28790 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  me()], and [sqli
287a0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
287b0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
287c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
287d0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
287e0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
287f0 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  void*, int n, vo
28800 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
28810 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
28820 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
28830 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c  tmt*, int, doubl
28840 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  e);.int sqlite3_
28850 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33  bind_int(sqlite3
28860 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
28870 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
28880 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ind_int64(sqlite
28890 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71  3_stmt*, int, sq
288a0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e  lite3_int64);.in
288b0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  t sqlite3_bind_n
288c0 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ull(sqlite3_stmt
288d0 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c  *, int);.int sql
288e0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73  ite3_bind_text(s
288f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
28900 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  t, const char*, 
28910 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76  int n, void(*)(v
28920 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
28930 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
28940 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
28950 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
28960 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
28970 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
28980 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71  e3_bind_value(sq
28990 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
289a0 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f  , const sqlite3_
289b0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
289c0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
289d0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
289e0 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a  , int, int n);..
289f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28a00 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61  Number Of SQL Pa
28a10 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e  rameters.**.** ^
28a20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
28a30 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64   be used to find
28a40 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b   the number of [
28a50 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a  SQL parameters].
28a60 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65  ** in a [prepare
28a70 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53  d statement].  S
28a80 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  QL parameters ar
28a90 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a  e tokens of the.
28aa0 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e  ** form "?", "?N
28ab0 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41  NN", ":AAA", "$A
28ac0 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74  AA", or "@AAA" t
28ad0 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20  hat serve as.** 
28ae0 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
28af0 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65   values that are
28b00 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
28b10 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20  lob | bound].** 
28b20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
28b30 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d  s at a later tim
28b40 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  e..**.** ^(This 
28b50 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79  routine actually
28b60 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64   returns the ind
28b70 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ex of the larges
28b80 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a  t (rightmost).**
28b90 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20   parameter. For 
28ba0 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74  all forms except
28bb0 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c   ?NNN, this will
28bc0 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74   correspond to t
28bd0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
28be0 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72  unique parameter
28bf0 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72  s.  If parameter
28c00 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f  s of the ?NNN fo
28c10 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20  rm are used,.** 
28c20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70  there may be gap
28c30 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e  s in the list.)^
28c40 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
28c50 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
28c60 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
28c70 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
28c80 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
28c90 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  name()], and.** 
28ca0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
28cb0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
28cc0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
28cd0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
28ce0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
28cf0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
28d00 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41  I3REF: Name Of A
28d10 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a   Host Parameter.
28d20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
28d30 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
28d40 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65  r_name(P,N) inte
28d50 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
28d60 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
28d70 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d   N-th [SQL param
28d80 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72  eter] in the [pr
28d90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28da0 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61  ] P..** ^(SQL pa
28db0 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
28dc0 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  form "?NNN" or "
28dd0 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
28de0 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76  or "$AAA".** hav
28df0 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69  e a name which i
28e00 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e  s the string "?N
28e10 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
28e20 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
28e30 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ".** respectivel
28e40 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  y..** In other w
28e50 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61  ords, the initia
28e60 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20  l ":" or "$" or 
28e70 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73  "@" or "?".** is
28e80 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72   included as par
28e90 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e  t of the name.)^
28ea0 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20  .** ^Parameters 
28eb0 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20  of the form "?" 
28ec0 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77  without a follow
28ed0 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65  ing integer have
28ee0 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20   no name.** and 
28ef0 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20  are referred to 
28f00 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72  as "nameless" or
28f10 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61   "anonymous para
28f20 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e  meters"..**.** ^
28f30 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70  The first host p
28f40 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
28f50 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20  index of 1, not 
28f60 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  0..**.** ^If the
28f70 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20   value N is out 
28f80 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74  of range or if t
28f90 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65  he N-th paramete
28fa0 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73  r is.** nameless
28fb0 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72  , then NULL is r
28fc0 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72  eturned.  ^The r
28fd0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
28fe0 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55  s.** always in U
28ff0 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76  TF-8 encoding ev
29000 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20  en if the named 
29010 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a  parameter was.**
29020 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63   originally spec
29030 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20  ified as UTF-16 
29040 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  in [sqlite3_prep
29050 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b  are16()] or.** [
29060 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
29070 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
29080 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
29090 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
290a0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
290b0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
290c0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
290d0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
290e0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
290f0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f  _index()]..*/.co
29100 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
29110 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
29120 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
29130 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mt*, int);../*.*
29140 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65  * CAPI3REF: Inde
29150 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72  x Of A Parameter
29160 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61   With A Given Na
29170 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  me.**.** ^Return
29180 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   the index of an
29190 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67   SQL parameter g
291a0 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20  iven its name.  
291b0 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61  ^The.** index va
291c0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20  lue returned is 
291d0 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65  suitable for use
291e0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
291f0 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  * parameter to [
29200 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
29210 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
29220 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69  ].  ^A zero.** i
29230 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f  s returned if no
29240 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65   matching parame
29250 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e  ter is found.  ^
29260 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  The parameter.**
29270 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69   name must be gi
29280 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65  ven in UTF-8 eve
29290 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61  n if the origina
292a0 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77  l statement.** w
292b0 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d  as prepared from
292c0 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69   UTF-16 text usi
292d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
292e0 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
292f0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
29300 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
29310 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
29320 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
29330 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
29340 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
29350 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
29360 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
29370 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
29380 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
29390 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ex(sqlite3_stmt*
293a0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
293b0 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ame);../*.** CAP
293c0 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c  I3REF: Reset All
293d0 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50   Bindings On A P
293e0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
293f0 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72  t.**.** ^Contrar
29400 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69  y to the intuiti
29410 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c  on of many, [sql
29420 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f  ite3_reset()] do
29430 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20  es not reset.** 
29440 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
29450 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67  d_blob | binding
29460 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  s] on a [prepare
29470 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
29480 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69   ^Use this routi
29490 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20  ne to reset all 
294a0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
294b0 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20  to NULL..*/.int 
294c0 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
294d0 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
294e0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
294f0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
29500 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52  f Columns In A R
29510 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20  esult Set.**.** 
29520 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62  ^Return the numb
29530 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
29540 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
29550 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
29560 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
29570 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72  tement]. ^This r
29580 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
29590 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20   if pStmt is an 
295a0 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
295b0 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72   that does not r
295c0 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20  eturn data (for 
295d0 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41  example an [UPDA
295e0 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  TE])..**.** See 
295f0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64  also: [sqlite3_d
29600 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  ata_count()].*/.
29610 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
29620 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  mn_count(sqlite3
29630 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
29640 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29650 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20  Column Names In 
29660 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a  A Result Set.**.
29670 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
29680 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  es return the na
29690 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61  me assigned to a
296a0 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75   particular colu
296b0 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73  mn.** in the res
296c0 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
296d0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
296e0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63    ^The sqlite3_c
296f0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20  olumn_name().** 
29700 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
29710 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
29720 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
29730 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
29740 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
29750 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74  umn_name16() ret
29760 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
29770 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
29780 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
29790 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73  ring.  ^The firs
297a0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
297b0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
297c0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20  tement].** that 
297d0 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b  implements the [
297e0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
297f0 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  t. ^The second p
29800 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
29810 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  ** column number
29820 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  .  ^The leftmost
29830 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65   column is numbe
29840 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r 0..**.** ^The 
29850 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
29860 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64  pointer is valid
29870 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68   until either th
29880 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
29890 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73  ement].** is des
298a0 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
298b0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
298c0 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
298d0 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
298e0 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
298f0 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
29900 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
29910 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
29920 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
29930 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
29940 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  next call to.** 
29950 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
29960 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ame() or sqlite3
29970 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
29980 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   on the same col
29990 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73  umn..**.** ^If s
299a0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
299b0 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65  fails during the
299c0 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65   processing of e
299d0 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a  ither routine.**
299e0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75   (for example du
299f0 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f  ring a conversio
29a00 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20  n from UTF-8 to 
29a10 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a  UTF-16) then a.*
29a20 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
29a30 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
29a40 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61  * ^The name of a
29a50 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
29a60 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
29a70 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66  he "AS" clause f
29a80 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d  or.** that colum
29a90 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61  n, if there is a
29aa0 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66  n AS clause.  If
29ab0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20   there is no AS 
29ac0 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74  clause.** then t
29ad0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
29ae0 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69  olumn is unspeci
29af0 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61  fied and may cha
29b00 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20  nge from.** one 
29b10 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
29b20 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a  e to the next..*
29b30 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
29b40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
29b50 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
29b60 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76   int N);.const v
29b70 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
29b80 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  umn_name16(sqlit
29b90 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
29ba0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
29bb0 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74  F: Source Of Dat
29bc0 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73  a In A Query Res
29bd0 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ult.**.** ^These
29be0 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64   routines provid
29bf0 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74  e a means to det
29c00 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62  ermine the datab
29c10 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a  ase, table, and.
29c20 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  ** table column 
29c30 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67  that is the orig
29c40 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c  in of a particul
29c50 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ar result column
29c60 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20   in.** [SELECT] 
29c70 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54  statement..** ^T
29c80 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
29c90 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65  atabase or table
29ca0 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62   or column can b
29cb0 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a  e returned as.**
29cc0 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20   either a UTF-8 
29cd0 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
29ce0 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73  .  ^The _databas
29cf0 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
29d00 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  rn.** the databa
29d10 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61  se name, the _ta
29d20 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ble_ routines re
29d30 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e  turn the table n
29d40 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20  ame, and.** the 
29d50 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73  origin_ routines
29d60 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75   return the colu
29d70 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65  mn name..** ^The
29d80 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
29d90 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
29da0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
29db0 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74  atement] is dest
29dc0 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b  royed.** using [
29dd0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
29de0 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
29df0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75   statement is au
29e00 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72  tomatically.** r
29e10 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65  eprepared by the
29e20 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b   first call to [
29e30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
29e40 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
29e50 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c   run.** or until
29e60 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
29e70 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74  ation is request
29e80 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61  ed.** again in a
29e90 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64   different encod
29ea0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ing..**.** ^The 
29eb0 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61  names returned a
29ec0 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  re the original 
29ed0 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73  un-aliased names
29ee0 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   of the.** datab
29ef0 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20  ase, table, and 
29f00 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  column..**.** ^T
29f10 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
29f20 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  t to these inter
29f30 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70  faces is a [prep
29f40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
29f50 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74  .** ^These funct
29f60 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ions return info
29f70 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68  rmation about th
29f80 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c  e Nth result col
29f90 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a  umn returned by.
29fa0 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
29fb0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
29fc0 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e   second function
29fd0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
29fe0 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c  he left-most col
29ff0 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20  umn is column 0 
2a000 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e  for these routin
2a010 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  es..**.** ^If th
2a020 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74  e Nth column ret
2a030 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61  urned by the sta
2a040 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70  tement is an exp
2a050 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75  ression or.** su
2a060 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f  bquery and is no
2a070 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65  t a column value
2a080 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68  , then all of th
2a090 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
2a0a0 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e  turn.** NULL.  ^
2a0b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69  These routine mi
2a0c0 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20  ght also return 
2a0d0 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79  NULL if a memory
2a0e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
2a0f0 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f  r.** occurs.  ^O
2a100 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72  therwise, they r
2a110 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f  eturn the name o
2a120 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64  f the attached d
2a130 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a  atabase, table,.
2a140 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61  ** or column tha
2a150 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63  t query result c
2a160 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63  olumn was extrac
2a170 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20  ted from..**.** 
2a180 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68  ^As with all oth
2a190 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20  er SQLite APIs, 
2a1a0 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65  those whose name
2a1b0 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20  s end with "16" 
2a1c0 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36  return.** UTF-16
2a1d0 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73   encoded strings
2a1e0 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66   and the other f
2a1f0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
2a200 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  UTF-8..**.** ^Th
2a210 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c  ese APIs are onl
2a220 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74  y available if t
2a230 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63  he library was c
2a240 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
2a250 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
2a260 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41  LE_COLUMN_METADA
2a270 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73  TA] C-preprocess
2a280 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a  or symbol..**.**
2a290 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
2a2a0 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
2a2b0 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73   or more of thes
2a2c0 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e  e routines again
2a2d0 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70  st the same.** p
2a2e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a2f0 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20  t and column at 
2a300 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
2a310 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
2a320 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  re.** undefined.
2a330 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
2a340 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
2a350 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  ll one or more.*
2a360 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2a370 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20  n_database_name 
2a380 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74  | column metadat
2a390 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a  a interfaces].**
2a3a0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70   for the same [p
2a3b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a3c0 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f  t] and result co
2a3d0 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73  lumn.** at the s
2a3e0 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
2a3f0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2a400 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73  defined..*/.cons
2a410 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2a420 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
2a430 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
2a440 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
2a450 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2a460 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
2a470 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2a480 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
2a490 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2a4a0 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71  mn_table_name(sq
2a4b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2a4c0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2a4d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
2a4e0 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  le_name16(sqlite
2a4f0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
2a500 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2a510 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
2a520 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
2a530 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
2a540 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2a550 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31  umn_origin_name1
2a560 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2a570 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2a580 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20  I3REF: Declared 
2a590 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75  Datatype Of A Qu
2a5a0 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a  ery Result.**.**
2a5b0 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72   ^(The first par
2a5c0 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65  ameter is a [pre
2a5d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a5e0 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61  ..** If this sta
2a5f0 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c  tement is a [SEL
2a600 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61  ECT] statement a
2a610 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  nd the Nth colum
2a620 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75  n of the.** retu
2a630 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20  rned result set 
2a640 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d  of that [SELECT]
2a650 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75   is a table colu
2a660 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78  mn (not an.** ex
2a670 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
2a680 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64  uery) then the d
2a690 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20  eclared type of 
2a6a0 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c  the table.** col
2a6b0 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  umn is returned.
2a6c0 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20  )^  ^If the Nth 
2a6d0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
2a6e0 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a  sult set is an.*
2a6f0 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
2a700 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61  subquery, then a
2a710 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
2a720 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54   returned..** ^T
2a730 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
2a740 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46  ng is always UTF
2a750 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a  -8 encoded..**.*
2a760 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
2a770 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62   given the datab
2a780 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a  ase schema:.**.*
2a790 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74  * CREATE TABLE t
2a7a0 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a  1(c1 VARIANT);.*
2a7b0 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c  *.** and the fol
2a7c0 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  lowing statement
2a7d0 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a   to be compiled:
2a7e0 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31  .**.** SELECT c1
2a7f0 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31   + 1, c1 FROM t1
2a800 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ;.**.** this rou
2a810 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72  tine would retur
2a820 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41  n the string "VA
2a830 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73  RIANT" for the s
2a840 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20  econd result.** 
2a850 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61  column (i==1), a
2a860 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nd a NULL pointe
2a870 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  r for the first 
2a880 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69  result column (i
2a890 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53  ==0).)^.**.** ^S
2a8a0 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
2a8b0 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69  ic run-time typi
2a8c0 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65  ng.  ^So just be
2a8d0 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a  cause a column.*
2a8e0 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f  * is declared to
2a8f0 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69   contain a parti
2a900 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20  cular type does 
2a910 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68  not mean that th
2a920 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64  e.** data stored
2a930 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20   in that column 
2a940 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72  is of the declar
2a950 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65  ed type.  SQLite
2a960 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20   is.** strongly 
2a970 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74  typed, but the t
2a980 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63  yping is dynamic
2a990 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54   not static.  ^T
2a9a0 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69  ype.** is associ
2a9b0 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69  ated with indivi
2a9c0 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74  dual values, not
2a9d0 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69   with the contai
2a9e0 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20  ners.** used to 
2a9f0 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65  hold those value
2aa00 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  s..*/.const char
2aa10 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2aa20 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65  _decltype(sqlite
2aa30 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
2aa40 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2aa50 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
2aa60 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2aa70 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
2aa80 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74  API3REF: Evaluat
2aa90 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  e An SQL Stateme
2aaa0 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61  nt.**.** After a
2aab0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2aac0 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70  ment] has been p
2aad0 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69  repared using ei
2aae0 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
2aaf0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2ab00 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2ab10 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  re16_v2()] or on
2ab20 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a  e of the legacy.
2ab30 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73  ** interfaces [s
2ab40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2ab50 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
2ab60 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73  epare16()], this
2ab70 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73   function.** mus
2ab80 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20  t be called one 
2ab90 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f  or more times to
2aba0 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74   evaluate the st
2abb0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  atement..**.** T
2abc0 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68  he details of th
2abd0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
2abe0 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
2abf0 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e   interface depen
2ac00 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20  d.** on whether 
2ac10 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61  the statement wa
2ac20 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  s prepared using
2ac30 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20   the newer "v2" 
2ac40 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71  interface.** [sq
2ac50 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2ac60 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2ac70 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2ac80 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65   or the older le
2ac90 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
2aca0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
2acb0 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
2acc0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e  e3_prepare16()].
2acd0 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
2ace0 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74  .** new "v2" int
2acf0 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
2ad00 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70  ended for new ap
2ad10 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74  plications but t
2ad20 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
2ad30 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74  erface will cont
2ad40 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f  inue to be suppo
2ad50 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20  rted..**.** ^In 
2ad60 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
2ad70 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e  face, the return
2ad80 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65   value will be e
2ad90 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55  ither [SQLITE_BU
2ada0 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  SY],.** [SQLITE_
2adb0 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  DONE], [SQLITE_R
2adc0 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  OW], [SQLITE_ERR
2add0 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OR], or [SQLITE_
2ade0 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74  MISUSE]..** ^Wit
2adf0 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
2ae00 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65  face, any of the
2ae10 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63   other [result c
2ae20 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  odes] or.** [ext
2ae30 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
2ae40 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  es] might be ret
2ae50 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a  urned as well..*
2ae60 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55  *.** ^[SQLITE_BU
2ae70 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SY] means that t
2ae80 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
2ae90 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f  ne was unable to
2aea0 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20   acquire the.** 
2aeb0 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69  database locks i
2aec0 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74  t needs to do it
2aed0 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20  s job.  ^If the 
2aee0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
2aef0 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63  COMMIT].** or oc
2af00 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20  curs outside of 
2af10 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
2af20 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f  saction, then yo
2af30 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a  u can retry the.
2af40 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49  ** statement.  I
2af50 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
2af60 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54  is not a [COMMIT
2af70 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74  ] and occurs wit
2af80 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63  hin an.** explic
2af90 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  it transaction t
2afa0 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72  hen you should r
2afb0 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ollback the tran
2afc0 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a  saction before.*
2afd0 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a  * continuing..**
2afe0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e  .** ^[SQLITE_DON
2aff0 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
2b000 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
2b010 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
2b020 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
2b030 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
2b040 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
2b050 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
2b060 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
2b070 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
2b080 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
2b090 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2b0a0 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
2b0b0 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
2b0c0 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
2b0d0 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
2b0e0 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73  ** ^If the SQL s
2b0f0 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65  tatement being e
2b100 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20  xecuted returns 
2b110 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b  any data, then [
2b120 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69  SQLITE_ROW].** i
2b130 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20  s returned each 
2b140 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f  time a new row o
2b150 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20  f data is ready 
2b160 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62  for processing b
2b170 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e  y the.** caller.
2b180 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20   The values may 
2b190 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e  be accessed usin
2b1a0 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63  g the [column ac
2b1b0 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e  cess functions].
2b1c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
2b1d0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61  () is called aga
2b1e0 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74  in to retrieve t
2b1f0 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64  he next row of d
2b200 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ata..**.** ^[SQL
2b210 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73  ITE_ERROR] means
2b220 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65   that a run-time
2b230 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20   error (such as 
2b240 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  a constraint.** 
2b250 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f  violation) has o
2b260 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65  ccurred.  sqlite
2b270 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
2b280 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
2b290 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d  ain on.** the VM
2b2a0 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69  . More informati
2b2b0 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20  on may be found 
2b2c0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
2b2d0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
2b2e0 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61  * ^With the lega
2b2f0 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20  cy interface, a 
2b300 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
2b310 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78  ror code (for ex
2b320 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ample,.** [SQLIT
2b330 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53  E_INTERRUPT], [S
2b340 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b  QLITE_SCHEMA], [
2b350 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c  SQLITE_CORRUPT],
2b360 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a   and so forth).*
2b370 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  * can be obtaine
2b380 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
2b390 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2b3a0 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
2b3b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
2b3c0 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
2b3d0 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d  erface,.** the m
2b3e0 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
2b3f0 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
2b400 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20  ned directly by 
2b410 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a  sqlite3_step()..
2b420 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  **.** [SQLITE_MI
2b430 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  SUSE] means that
2b440 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e   the this routin
2b450 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61  e was called ina
2b460 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a  ppropriately..**
2b470 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20   Perhaps it was 
2b480 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65  called on a [pre
2b490 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2b4a0 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72   that has.** alr
2b4b0 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74  eady been [sqlit
2b4c0 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
2b4d0 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f  nalized] or on o
2b4e0 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70  ne that had.** p
2b4f0 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
2b500 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ed [SQLITE_ERROR
2b510 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
2b520 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64  E].  Or it could
2b530 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20  .** be the case 
2b540 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61  that the same da
2b550 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2b560 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  n is being used 
2b570 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72  by two or.** mor
2b580 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  e threads at the
2b590 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20   same moment in 
2b5a0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  time..**.** For 
2b5b0 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  all versions of 
2b5c0 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64  SQLite up to and
2b5d0 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32   including 3.6.2
2b5e0 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  3.1, a call to.*
2b5f0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2b600 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64  ()] was required
2b610 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73   after sqlite3_s
2b620 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61  tep() returned a
2b630 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  nything.** other
2b640 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
2b650 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75  W] before any su
2b660 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
2b670 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65  ion of.** sqlite
2b680 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75  3_step().  Failu
2b690 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  re to reset the 
2b6a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b6b0 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  nt using .** [sq
2b6c0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
2b6d0 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
2b6e0 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
2b6f0 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a  ] return from.**
2b700 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
2b710 20 20 42 75 74 20 61 66 74 65 72 20 76 65 72 73    But after vers
2b720 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71  ion 3.6.23.1, sq
2b730 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 67  lite3_step() beg
2b740 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73  an.** calling [s
2b750 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2b760 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e  automatically in
2b770 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e   this circumstan
2b780 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61  ce rather.** tha
2b790 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  n returning [SQL
2b7a0 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68  ITE_MISUSE].  Th
2b7b0 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64  is is not consid
2b7c0 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69  ered a compatibi
2b7d0 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65  lity.** break be
2b7e0 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63  cause any applic
2b7f0 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20  ation that ever 
2b800 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49  receives an SQLI
2b810 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a  TE_MISUSE error.
2b820 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20  ** is broken by 
2b830 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65  definition.  The
2b840 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
2b850 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65  TORESET] compile
2b860 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20  -time option.** 
2b870 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
2b880 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63  estore the legac
2b890 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  y behavior..**.*
2b8a0 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72  * <b>Goofy Inter
2b8b0 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20  face Alert:</b> 
2b8c0 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
2b8d0 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c  terface, the sql
2b8e0 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41  ite3_step().** A
2b8f0 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  PI always return
2b900 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f  s a generic erro
2b910 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f  r code, [SQLITE_
2b920 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e  ERROR], followin
2b930 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f  g any.** error o
2b940 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
2b950 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c  E_BUSY] and [SQL
2b960 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f  ITE_MISUSE].  Yo
2b970 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b  u must call.** [
2b980 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2b990 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
2b9a0 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65  alize()] in orde
2b9b0 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66  r to find one of
2b9c0 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
2b9d0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74   [error codes] t
2b9e0 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72  hat better descr
2b9f0 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a  ibes the error..
2ba00 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ** We admit that
2ba10 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79   this is a goofy
2ba20 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72   design.  The pr
2ba30 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66  oblem has been f
2ba40 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ixed.** with the
2ba50 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e   "v2" interface.
2ba60 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65    If you prepare
2ba70 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c   all of your SQL
2ba80 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75   statements.** u
2ba90 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
2baa0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2bab0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
2bac0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69  repare16_v2()] i
2bad0 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65  nstead.** of the
2bae0 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33   legacy [sqlite3
2baf0 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
2bb00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2bb10 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  16()] interfaces
2bb20 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f  ,.** then the mo
2bb30 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  re specific [err
2bb40 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65  or codes] are re
2bb50 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a  turned directly.
2bb60 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ** by sqlite3_st
2bb70 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f  ep().  The use o
2bb80 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  f the "v2" inter
2bb90 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
2bba0 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ded..*/.int sqli
2bbb0 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33  te3_step(sqlite3
2bbc0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
2bbd0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
2bbe0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
2bbf0 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a   result set.**.*
2bc00 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
2bc10 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74  ata_count(P) int
2bc20 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2bc30 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
2bc40 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63  umns in the.** c
2bc50 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
2bc60 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
2bc70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2bc80 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70  ent] P..** ^If p
2bc90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2bca0 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  t P does not hav
2bcb0 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20  e results ready 
2bcc0 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69  to return.** (vi
2bcd0 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b  a calls to the [
2bce0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
2bcf0 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt | sqlite3_col
2bd00 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69  umn_*()] of.** i
2bd10 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20  nterfaces) then 
2bd20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2bd30 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e  nt(P) returns 0.
2bd40 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2bd50 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
2bd60 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75  outine also retu
2bd70 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20  rns 0 if P is a 
2bd80 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
2bd90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
2bda0 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
2bdb0 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66  ine returns 0 if
2bdc0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
2bdd0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
2bde0 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
2bdf0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ned [SQLITE_DONE
2be00 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
2be10 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a  _data_count(P).*
2be20 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f  * will return no
2be30 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f  n-zero if previo
2be40 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  us call to [sqli
2be50 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74  te3_step](P) ret
2be60 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  urned.** [SQLITE
2be70 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e  _ROW], except in
2be80 20 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65   the case of the
2be90 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65   [PRAGMA increme
2bea0 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20  ntal_vacuum].** 
2beb0 77 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20  where it always 
2bec0 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e  returns zero sin
2bed0 63 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20  ce each step of 
2bee0 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a  that multi-step.
2bef0 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e  ** pragma return
2bf00 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64  s 0 columns of d
2bf10 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ata..**.** See a
2bf20 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  lso: [sqlite3_co
2bf30 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f  lumn_count()].*/
2bf40 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74  .int sqlite3_dat
2bf50 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  a_count(sqlite3_
2bf60 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2bf70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
2bf80 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74  undamental Datat
2bf90 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ypes.** KEYWORDS
2bfa0 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a  : SQLITE_TEXT.**
2bfb0 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75  .** ^(Every valu
2bfc0 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20  e in SQLite has 
2bfd0 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64  one of five fund
2bfe0 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65  amental datatype
2bff0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
2c000 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67   <li> 64-bit sig
2c010 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  ned integer.** <
2c020 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20  li> 64-bit IEEE 
2c030 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
2c040 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74  umber.** <li> st
2c050 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f  ring.** <li> BLO
2c060 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a  B.** <li> NULL.*
2c070 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
2c080 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
2c090 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61  are codes for ea
2c0a0 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65  ch of those type
2c0b0 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
2c0c0 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  at the SQLITE_TE
2c0d0 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20  XT constant was 
2c0e0 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c  also used in SQL
2c0f0 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a  ite version 2.**
2c100 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c   for a completel
2c110 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e  y different mean
2c120 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ing.  Software t
2c130 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73  hat links agains
2c140 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65  t both.** SQLite
2c150 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53   version 2 and S
2c160 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20  QLite version 3 
2c170 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54  should use SQLIT
2c180 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20  E3_TEXT, not.** 
2c190 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a  SQLITE_TEXT..*/.
2c1a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
2c1b0 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e  NTEGER  1.#defin
2c1c0 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20  e SQLITE_FLOAT  
2c1d0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
2c1e0 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64  TE_BLOB     4.#d
2c1f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c  efine SQLITE_NUL
2c200 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53  L     5.#ifdef S
2c210 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64  QLITE_TEXT.# und
2c220 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
2c230 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51  else.# define SQ
2c240 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a  LITE_TEXT     3.
2c250 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53  #endif.#define S
2c260 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20  QLITE3_TEXT     
2c270 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  3../*.** CAPI3RE
2c280 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73  F: Result Values
2c290 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a   From A Query.**
2c2a0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75   KEYWORDS: {colu
2c2b0 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
2c2c0 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ons}.**.** These
2c2d0 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74   routines form t
2c2e0 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 22 20  he "result set" 
2c2f0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
2c300 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
2c310 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
2c320 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67  ion about a sing
2c330 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  le column of the
2c340 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75   current.** resu
2c350 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72  lt row of a quer
2c360 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61  y.  ^In every ca
2c370 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67  se the first arg
2c380 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
2c390 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72  er.** to the [pr
2c3a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c3b0 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20  ] that is being 
2c3c0 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b  evaluated (the [
2c3d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a  sqlite3_stmt*].*
2c3e0 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  * that was retur
2c3f0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
2c400 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2c410 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61  or one of its va
2c420 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74  riants).** and t
2c430 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
2c440 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
2c450 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f  of the column fo
2c460 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74  r which informat
2c470 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
2c480 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20   returned. ^The 
2c490 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
2c4a0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2c4b0 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20  t has the index 
2c4c0 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65  0..** ^The numbe
2c4d0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2c4e0 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62  the result can b
2c4f0 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
2c500 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
2c510 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a  olumn_count()]..
2c520 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  **.** If the SQL
2c530 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
2c540 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f  not currently po
2c550 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72  int to a valid r
2c560 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a  ow, or if the.**
2c570 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73   column index is
2c580 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74   out of range, t
2c590 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  he result is und
2c5a0 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65  efined..** These
2c5b0 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e   routines may on
2c5c0 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  ly be called whe
2c5d0 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
2c5e0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
2c5f0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
2c600 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  s returned [SQLI
2c610 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74  TE_ROW] and neit
2c620 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
2c630 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71  reset()] nor [sq
2c640 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2c650 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  ] have been call
2c660 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e  ed subsequently.
2c670 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68  .** If any of th
2c680 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
2c690 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73   called after [s
2c6a0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2c6b0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
2c6c0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  inalize()] or af
2c6d0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ter [sqlite3_ste
2c6e0 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
2c6f0 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f  d.** something o
2c700 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
2c710 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75  E_ROW], the resu
2c720 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
2c730 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65  d..** If [sqlite
2c740 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
2c750 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2c760 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2c770 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61  ize()].** are ca
2c780 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66  lled from a diff
2c790 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69  erent thread whi
2c7a0 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  le any of these 
2c7b0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
2c7c0 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68  pending, then th
2c7d0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2c7e0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
2c7f0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
2c800 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e  mn_type() routin
2c810 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
2c820 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
2c830 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65   | datatype code
2c840 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61  ] for the initia
2c850 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f  l data type.** o
2c860 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c  f the result col
2c870 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72  umn.  ^The retur
2c880 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65  ned value is one
2c890 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45   of [SQLITE_INTE
2c8a0 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  GER],.** [SQLITE
2c8b0 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45  _FLOAT], [SQLITE
2c8c0 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  _TEXT], [SQLITE_
2c8d0 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  BLOB], or [SQLIT
2c8e0 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61  E_NULL].  The va
2c8f0 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
2c900 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2c910 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79  n_type() is only
2c920 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e   meaningful if n
2c930 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72  o type.** conver
2c940 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72  sions have occur
2c950 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64  red as described
2c960 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61   below.  After a
2c970 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
2c980 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72  ,.** the value r
2c990 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2c9a0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2c9b0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
2c9c0 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f  Future.** versio
2c9d0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ns of SQLite may
2c9e0 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61   change the beha
2c9f0 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
2ca00 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a  column_type().**
2ca10 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70   following a typ
2ca20 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  e conversion..**
2ca30 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2ca40 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
2ca50 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65  UTF-8 string the
2ca60 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
2ca70 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
2ca80 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2ca90 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2caa0 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
2cab0 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
2cac0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2cad0 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
2cae0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
2caf0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f  olumn_bytes() co
2cb00 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
2cb10 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e  ring to UTF-8 an
2cb20 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
2cb30 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2cb40 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  es..** ^If the r
2cb50 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
2cb60 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
2cb70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2cb80 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  es() uses.** [sq
2cb90 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
2cba0 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
2cbb0 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
2cbc0 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  -8 string and re
2cbd0 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
2cbe0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2cbf0 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
2cc00 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2cc10 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c  s NULL, then sql
2cc20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2cc30 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  s() returns zero
2cc40 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2cc50 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
2cc60 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
2cc70 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
2cc80 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2cc90 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  6().** routine r
2cca0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2ccb0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2ccc0 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
2ccd0 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
2cce0 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20  sult is a UTF-8 
2ccf0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
2cd00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2cd10 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  s16() converts.*
2cd20 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
2cd30 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20  UTF-16 and then 
2cd40 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2cd50 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
2cd60 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2cd70 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
2cd80 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
2cd90 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2cda0 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
2cdb0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
2cdc0 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
2cdd0 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73  ue to a UTF-16 s
2cde0 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
2cdf0 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
2ce00 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2ce10 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
2ce20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55  the result is NU
2ce30 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  LL, then sqlite3
2ce40 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2ce50 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
2ce60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65  **.** ^The value
2ce70 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
2ce80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2ce90 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b  tes()] and .** [
2cea0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2ceb0 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74  ytes16()] do not
2cec0 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72   include the zer
2ced0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74  o terminators at
2cee0 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74   the end.** of t
2cef0 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72  he string.  ^For
2cf00 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61   clarity: the va
2cf10 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
2cf20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2cf30 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
2cf40 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2cf50 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20  _bytes16()] are 
2cf60 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
2cf70 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74   bytes in the st
2cf80 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75  ring, not the nu
2cf90 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
2cfa0 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e  rs..**.** ^Strin
2cfb0 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  gs returned by s
2cfc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2cfd0 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  xt() and sqlite3
2cfe0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2cff0 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20  ,.** even empty 
2d000 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77  strings, are alw
2d010 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
2d020 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72  ted.  ^The retur
2d030 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20  n.** value from 
2d040 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2d050 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f  lob() for a zero
2d060 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20  -length BLOB is 
2d070 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
2d080 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63  **.** ^The objec
2d090 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  t returned by [s
2d0a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
2d0b0 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20  lue()] is an.** 
2d0c0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
2d0d0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2d0e0 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63  ct.  An unprotec
2d0f0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2d100 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20  e object.** may 
2d110 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
2d120 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  h [sqlite3_bind_
2d130 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
2d140 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
2d150 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  ue()]..** If the
2d160 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2d170 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2d180 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
2d190 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2d1a0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
2d1b0 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72  sed in any other
2d1c0 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20   way, including 
2d1d0 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74  calls.** to rout
2d1e0 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
2d1f0 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c  e3_value_int()],
2d200 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2d210 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
2d220 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2d230 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  tes()], then the
2d240 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
2d250 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  efined..**.** Th
2d260 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74  ese routines att
2d270 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20  empt to convert 
2d280 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20  the value where 
2d290 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46  appropriate.  ^F
2d2a0 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69  or.** example, i
2d2b0 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  f the internal r
2d2c0 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73  epresentation is
2d2d0 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78   FLOAT and a tex
2d2e0 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72  t result.** is r
2d2f0 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74  equested, [sqlit
2d300 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
2d310 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
2d320 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65  y to perform the
2d330 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61  .** conversion a
2d340 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e  utomatically.  ^
2d350 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  (The following t
2d360 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65  able details the
2d370 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20   conversions.** 
2d380 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64  that are applied
2d390 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
2d3a0 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
2d3b0 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
2d3c0 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c  r><th> Internal<
2d3d0 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71  br>Type <th> Req
2d3e0 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c  uested<br>Type <
2d3f0 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a  th>  Conversion.
2d400 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  **.** <tr><td>  
2d410 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54  NULL    <td> INT
2d420 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75  EGER   <td> Resu
2d430 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c  lt is 0.** <tr><
2d440 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
2d450 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
2d460 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a   Result is 0.0.*
2d470 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2d480 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
2d490 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2d4a0 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
2d4b0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2d4c0 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
2d4d0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2d4e0 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
2d4f0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
2d500 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20  ER  <td>  FLOAT 
2d510 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
2d520 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20  from integer to 
2d530 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
2d540 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
2d550 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
2d560 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
2d570 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a  f the integer.**
2d580 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
2d590 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20  R  <td>   BLOB  
2d5a0 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49    <td> Same as I
2d5b0 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20  NTEGER->TEXT.** 
2d5c0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
2d5d0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
2d5e0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
2d5f0 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65  om float to inte
2d600 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
2d610 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
2d620 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
2d630 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
2d640 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72  the float.** <tr
2d650 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
2d660 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
2d670 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54  d> Same as FLOAT
2d680 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
2d690 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
2d6a0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
2d6b0 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  Use atoi().** <t
2d6c0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
2d6d0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
2d6e0 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a  td> Use atof().*
2d6f0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
2d700 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
2d710 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67     <td> No chang
2d720 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  e.** <tr><td>  B
2d730 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOB    <td> INTE
2d740 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  GER   <td> Conve
2d750 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20  rt to TEXT then 
2d760 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  use atoi().** <t
2d770 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
2d780 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
2d790 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54  td> Convert to T
2d7a0 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f  EXT then use ato
2d7b0 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  f().** <tr><td> 
2d7c0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20   BLOB    <td>   
2d7d0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64  TEXT    <td> Add
2d7e0 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74   a zero terminat
2d7f0 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20  or if needed.** 
2d800 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c  </table>.** </bl
2d810 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
2d820 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76  * The table abov
2d830 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63  e makes referenc
2d840 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20  e to standard C 
2d850 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e  library function
2d860 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20  s atoi().** and 
2d870 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20  atof().  SQLite 
2d880 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20  does not really 
2d890 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69  use these functi
2d8a0 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73  ons.  It has its
2d8b0 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65  .** own equivale
2d8c0 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74  nt internal rout
2d8d0 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28  ines.  The atoi(
2d8e0 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d  ) and atof() nam
2d8f0 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69  es are.** used i
2d900 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20  n the table for 
2d910 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61  brevity and beca
2d920 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d  use they are fam
2d930 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a  iliar to most.**
2d940 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a   C programmers..
2d950 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
2d960 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72  when type conver
2d970 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69  sions occur, poi
2d980 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62  nters returned b
2d990 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73  y prior.** calls
2d9a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
2d9b0 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  mn_blob(), sqlit
2d9c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2d9d0 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69  , and/or.** sqli
2d9e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2d9f0 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c  6() may be inval
2da00 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20  idated..** Type 
2da10 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20  conversions and 
2da20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61  pointer invalida
2da30 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75  tions might occu
2da40 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c  r.** in the foll
2da50 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a  owing cases:.**.
2da60 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
2da70 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
2da80 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e  ent is a BLOB an
2da90 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2daa0 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20  _text() or.**   
2dab0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
2dac0 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
2dad0 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65  lled.  A zero-te
2dae0 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a  rminator might.*
2daf0 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62  *      need to b
2db00 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73  e added to the s
2db10 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  tring.</li>.** <
2db20 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
2db30 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38  content is UTF-8
2db40 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
2db50 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2db60 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
2db70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2db80 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
2db90 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
2dba0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
2dbb0 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31  **      to UTF-1
2dbc0 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  6.</li>.** <li> 
2dbd0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
2dbe0 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65  ent is UTF-16 te
2dbf0 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
2dc00 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
2dc10 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
2dc20 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69  _column_text() i
2dc30 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
2dc40 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
2dc50 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
2dc60 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a   to UTF-8.</li>.
2dc70 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
2dc80 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77  Conversions betw
2dc90 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64  een UTF-16be and
2dca0 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c   UTF-16le are al
2dcb0 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61  ways done in pla
2dcc0 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74  ce and do.** not
2dcd0 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72   invalidate a pr
2dce0 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f  ior pointer, tho
2dcf0 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68  ugh of course th
2dd00 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
2dd10 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
2dd20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  the prior pointe
2dd30 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c  r references wil
2dd40 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69  l have been modi
2dd50 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e  fied.  Other kin
2dd60 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73  ds.** of convers
2dd70 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20  ion are done in 
2dd80 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73  place when it is
2dd90 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73   possible, but s
2dda0 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a  ometimes they.**
2ddb0 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c   are not possibl
2ddc0 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63  e and in those c
2ddd0 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74  ases prior point
2dde0 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61  ers are invalida
2ddf0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ted..**.** The s
2de00 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73  afest and easies
2de10 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f  t to remember po
2de20 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b  licy is to invok
2de30 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
2de40 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68  .** in one of th
2de50 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73  e following ways
2de60 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
2de70 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
2de80 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f  umn_text() follo
2de90 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
2dea0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
2deb0 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
2dec0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2ded0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
2dee0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2def0 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
2df00 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
2df10 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65  text16() followe
2df20 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2df30 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c  umn_bytes16()</l
2df40 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
2df50 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
2df60 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c  , you should cal
2df70 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  l sqlite3_column
2df80 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69  _text(),.** sqli
2df90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2dfa0 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  ), or sqlite3_co
2dfb0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69  lumn_text16() fi
2dfc0 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65  rst to force the
2dfd0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20   result.** into 
2dfe0 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d  the desired form
2dff0 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20  at, then invoke 
2e000 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2e010 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  ytes() or.** sql
2e020 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2e030 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68  s16() to find th
2e040 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65  e size of the re
2e050 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69  sult.  Do not mi
2e060 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71  x calls.** to sq
2e070 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2e080 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  t() or sqlite3_c
2e090 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74  olumn_blob() wit
2e0a0 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  h calls to.** sq
2e0b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2e0c0 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e  es16(), and do n
2e0d0 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20  ot mix calls to 
2e0e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2e0f0 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20  ext16().** with 
2e100 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2e110 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e  _column_bytes().
2e120 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e  .**.** ^The poin
2e130 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72  ters returned ar
2e140 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20  e valid until a 
2e150 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20  type conversion 
2e160 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73  occurs as.** des
2e170 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72  cribed above, or
2e180 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f   until [sqlite3_
2e190 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
2e1a0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
2e1b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
2e1c0 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  lize()] is calle
2e1d0 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  d.  ^The memory 
2e1e0 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f  space used to ho
2e1f0 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e  ld strings.** an
2e200 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64  d BLOBs is freed
2e210 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
2e220 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70   Do <b>not</b> p
2e230 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73  ass the pointers
2e240 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71   returned.** [sq
2e250 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2e260 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  b()], [sqlite3_c
2e270 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65  olumn_text()], e
2e280 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c  tc. into.** [sql
2e290 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
2e2a0 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72  .** ^(If a memor
2e2b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
2e2c0 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
2e2d0 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20   the evaluation 
2e2e0 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
2e2f0 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64  se routines, a d
2e300 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20  efault value is 
2e310 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64  returned.  The d
2e320 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20  efault value.** 
2e330 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e  is either the in
2e340 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f  teger 0, the flo
2e350 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
2e360 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c  er 0.0, or a NUL
2e370 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53  L.** pointer.  S
2e380 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
2e390 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
2e3a0 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  ode()] will retu
2e3b0 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  rn.** [SQLITE_NO
2e3c0 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74  MEM].)^.*/.const
2e3d0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2e3e0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74  olumn_blob(sqlit
2e3f0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2e400 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
2e410 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71  _column_bytes(sq
2e420 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2e430 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
2e440 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2e450 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2e460 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75  , int iCol);.dou
2e470 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ble sqlite3_colu
2e480 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  mn_double(sqlite
2e490 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2e4a0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
2e4b0 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74  column_int(sqlit
2e4c0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2e4d0 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ol);.sqlite3_int
2e4e0 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  64 sqlite3_colum
2e4f0 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  n_int64(sqlite3_
2e500 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2e510 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
2e520 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2e530 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74  olumn_text(sqlit
2e540 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2e550 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ol);.const void 
2e560 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2e570 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
2e580 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2e590 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2e5a0 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33  umn_type(sqlite3
2e5b0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2e5c0 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  );.sqlite3_value
2e5d0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2e5e0 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
2e5f0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2e600 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e610 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70  : Destroy A Prep
2e620 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
2e630 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bject.**.** ^The
2e640 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2e650 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
2e660 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65  called to delete
2e670 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2e680 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20  tement]..** ^If 
2e690 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2e6a0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68  evaluation of th
2e6b0 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f  e statement enco
2e6c0 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72  untered no error
2e6d0 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73  s.** or if the s
2e6e0 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65  tatement is neve
2e6f0 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64  r been evaluated
2e700 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66  , then sqlite3_f
2e710 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e  inalize() return
2e720 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20  s.** SQLITE_OK. 
2e730 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
2e740 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  cent evaluation 
2e750 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66  of statement S f
2e760 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73  ailed, then.** s
2e770 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2e780 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61  S) returns the a
2e790 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
2e7a0 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  r code] or.** [e
2e7b0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
2e7c0 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
2e7d0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2e7e0 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  (S) routine can 
2e7f0 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79  be called at any
2e800 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a   point during.**
2e810 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20   the life cycle 
2e820 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
2e830 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65  tement] S:.** be
2e840 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53  fore statement S
2e850 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74   is ever evaluat
2e860 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65  ed, after.** one
2e870 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74   or more calls t
2e880 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
2e890 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e  ()], or after an
2e8a0 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71  y call.** to [sq
2e8b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
2e8c0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
2e8d0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73  her or not the s
2e8e0 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20  tatement has.** 
2e8f0 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74  completed execut
2e900 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f  ion..**.** ^Invo
2e910 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e  king sqlite3_fin
2e920 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c  alize() on a NUL
2e930 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68  L pointer is a h
2e940 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
2e950 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
2e960 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69  tion must finali
2e970 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72  ze every [prepar
2e980 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
2e990 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a   order to avoid.
2e9a0 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b  ** resource leak
2e9b0 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65  s.  It is a grie
2e9c0 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74  vous error for t
2e9d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  he application t
2e9e0 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20  o try to use.** 
2e9f0 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
2ea00 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61  ment after it ha
2ea10 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
2ea20 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20  .  Any use of a 
2ea30 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
2ea40 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68  ement after it h
2ea50 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
2ea60 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20  d can result in 
2ea70 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a  undefined and.**
2ea80 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68   undesirable beh
2ea90 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65  avior such as se
2eaa0 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70  gfaults and heap
2eab0 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a   corruption..*/.
2eac0 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  int sqlite3_fina
2ead0 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  lize(sqlite3_stm
2eae0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2eaf0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
2eb00 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  t A Prepared Sta
2eb10 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
2eb20 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2eb30 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  reset() function
2eb40 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65   is called to re
2eb50 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20  set a [prepared 
2eb60 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
2eb70 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73  ject back to its
2eb80 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20   initial state, 
2eb90 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65  ready to be re-e
2eba0 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79  xecuted..** ^Any
2ebb0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76   SQL statement v
2ebc0 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61  ariables that ha
2ebd0 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74  d values bound t
2ebe0 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20  o them using.** 
2ebf0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
2ec00 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
2ec10 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72  _bind_*() API] r
2ec20 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75  etain their valu
2ec30 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69  es..** Use [sqli
2ec40 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
2ec50 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  gs()] to reset t
2ec60 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a  he bindings..**.
2ec70 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
2ec80 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
2ec90 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20  face resets the 
2eca0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2ecb0 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74  ent] S.** back t
2ecc0 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
2ecd0 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a  of its program..
2ece0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
2ecf0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2ed00 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
2ed10 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
2ed20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ed30 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b  nt] S returned [
2ed40 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b  SQLITE_ROW] or [
2ed50 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a  SQLITE_DONE],.**
2ed60 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   or if [sqlite3_
2ed70 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76  step(S)] has nev
2ed80 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63  er before been c
2ed90 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74  alled on S,.** t
2eda0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  hen [sqlite3_res
2edb0 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b  et(S)] returns [
2edc0 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
2edd0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
2ede0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
2edf0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2ee00 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
2ee10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2ee20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65  S indicated an e
2ee30 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73  rror, then.** [s
2ee40 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2ee50 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72   returns an appr
2ee60 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
2ee70 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
2ee80 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2ee90 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f  S)] interface do
2eea0 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
2eeb0 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61  e values.** of a
2eec0 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ny [sqlite3_bind
2eed0 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20  _blob|bindings] 
2eee0 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  on the [prepared
2eef0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
2ef00 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
2ef10 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  set(sqlite3_stmt
2ef20 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2ef30 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74   CAPI3REF: Creat
2ef40 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51  e Or Redefine SQ
2ef50 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b  L Functions.** K
2ef60 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69  EYWORDS: {functi
2ef70 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
2ef80 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  ines}.** KEYWORD
2ef90 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
2efa0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2efb0 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  tion}.** KEYWORD
2efc0 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
2efd0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2efe0 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions}.**.** ^Th
2eff0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63  ese functions (c
2f000 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77  ollectively know
2f010 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63  n as "function c
2f020 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
2f030 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74  ").** are used t
2f040 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69  o add SQL functi
2f050 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
2f060 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65  s or to redefine
2f070 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
2f080 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c   of existing SQL
2f090 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
2f0a0 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f  gregates.  The o
2f0b0 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20  nly differences 
2f0c0 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65  between.** these
2f0d0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68   routines are th
2f0e0 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  e text encoding 
2f0f0 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20  expected for.** 
2f100 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
2f110 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f  eter (the name o
2f120 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62  f the function b
2f130 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a  eing created).**
2f140 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63   and the presenc
2f150 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20  e or absence of 
2f160 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c  a destructor cal
2f170 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65  lback for.** the
2f180 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
2f190 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  a pointer..**.**
2f1a0 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
2f1b0 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61  meter is the [da
2f1c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2f1d0 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20  n] to which the 
2f1e0 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  SQL.** function 
2f1f0 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20  is to be added. 
2f200 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74   ^If an applicat
2f210 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68  ion uses more th
2f220 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a  an one database.
2f230 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  ** connection th
2f240 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  en application-d
2f250 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2f260 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64  ions must be add
2f270 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61  ed.** to each da
2f280 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2f290 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  n separately..**
2f2a0 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
2f2b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2f2c0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c   name of the SQL
2f2d0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2f2e0 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65  created or.** re
2f2f0 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c  defined.  ^The l
2f300 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d  ength of the nam
2f310 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20  e is limited to 
2f320 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55  255 bytes in a U
2f330 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e  TF-8.** represen
2f340 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76  tation, exclusiv
2f350 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65  e of the zero-te
2f360 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65  rminator.  ^Note
2f370 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a   that the name.*
2f380 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69  * length limit i
2f390 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73  s in UTF-8 bytes
2f3a0 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73  , not characters
2f3b0 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65   nor UTF-16 byte
2f3c0 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74  s.  .** ^Any att
2f3d0 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61  empt to create a
2f3e0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
2f3f0 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20   longer name.** 
2f400 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b  will result in [
2f410 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62  SQLITE_MISUSE] b
2f420 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a  eing returned..*
2f430 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
2f440 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29  parameter (nArg)
2f450 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
2f460 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
2f470 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hat the SQL func
2f480 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
2f490 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20  gate takes. ^If 
2f4a0 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69  this parameter i
2f4b0 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53  s -1, then the S
2f4c0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
2f4d0 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20  * aggregate may 
2f4e0 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20  take any number 
2f4f0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74  of arguments bet
2f500 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c  ween 0 and the l
2f510 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b  imit.** set by [
2f520 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b  sqlite3_limit]([
2f530 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
2f540 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66  CTION_ARG]).  If
2f550 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
2f560 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20  rameter is less 
2f570 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74  than -1 or great
2f580 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e  er than 127 then
2f590 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
2f5a0 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
2f5b0 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
2f5c0 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78   parameter, eTex
2f5d0 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20  tRep, specifies 
2f5e0 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  what.** [SQLITE_
2f5f0 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f  UTF8 | text enco
2f600 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66  ding] this SQL f
2f610 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20  unction prefers 
2f620 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d  for.** its param
2f630 65 74 65 72 73 2e 20 20 45 76 65 72 79 20 53 51  eters.  Every SQ
2f640 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
2f650 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 62  mentation must b
2f660 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a  e able to work.*
2f670 2a 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54  * with UTF-8, UT
2f680 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31  F-16le, or UTF-1
2f690 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69  6be.  But some i
2f6a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
2f6b0 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66  ay be.** more ef
2f6c0 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65  ficient with one
2f6d0 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61   encoding than a
2f6e0 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70  nother.  ^An app
2f6f0 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20  lication may.** 
2f700 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
2f710 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2f720 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61   or sqlite3_crea
2f730 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20  te_function16() 
2f740 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65  multiple.** time
2f750 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
2f760 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74  function but wit
2f770 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75  h different valu
2f780 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a  es of eTextRep..
2f790 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c  ** ^When multipl
2f7a0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2f7b0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
2f7c0 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c  nction are avail
2f7d0 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  able, SQLite.** 
2f7e0 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e  will pick the on
2f7f0 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20  e that involves 
2f800 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
2f810 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73   of data convers
2f820 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65  ion..** If there
2f830 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c   is only a singl
2f840 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2f850 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20   which does not 
2f860 63 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a  care what text.*
2f870 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  * encoding is us
2f880 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75  ed, then the fou
2f890 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rth argument sho
2f8a0 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  uld be [SQLITE_A
2f8b0 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  NY]..**.** ^(The
2f8c0 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72   fifth parameter
2f8d0 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79   is an arbitrary
2f8e0 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69   pointer.  The i
2f8f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2f900 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
2f910 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73   can gain access
2f920 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72   to this pointer
2f930 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2f940 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a  user_data()].)^.
2f950 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68  **.** ^The sixth
2f960 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69  , seventh and ei
2f970 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c  ghth parameters,
2f980 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e   xFunc, xStep an
2f990 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a  d xFinal, are.**
2f9a0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c   pointers to C-l
2f9b0 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e  anguage function
2f9c0 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
2f9d0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2f9e0 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
2f9f0 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c  e. ^A scalar SQL
2fa00 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
2fa10 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
2fa20 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e  tion of the xFun
2fa30 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e  c.** callback on
2fa40 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ly; NULL pointer
2fa50 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  s must be passed
2fa60 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e   as the xStep an
2fa70 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61  d xFinal.** para
2fa80 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72  meters. ^An aggr
2fa90 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
2faa0 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
2fab0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2fac0 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46   xStep.** and xF
2fad0 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f  inal and NULL po
2fae0 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61  inter must be pa
2faf0 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20  ssed for xFunc. 
2fb00 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78  ^To delete an ex
2fb10 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75  isting.** SQL fu
2fb20 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
2fb30 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70  ate, pass NULL p
2fb40 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20  ointers for all 
2fb50 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a  three function.*
2fb60 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a  * callbacks..**.
2fb70 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74  ** ^(If the nint
2fb80 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2fb90 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2fba0 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e  nction_v2() is n
2fbb0 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e  ot NULL,.** then
2fbc0 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f   it is destructo
2fbd0 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63  r for the applic
2fbe0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
2fbf0 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74  er. .** The dest
2fc00 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65  ructor is invoke
2fc10 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74  d when the funct
2fc20 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20  ion is deleted, 
2fc30 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a  either by being.
2fc40 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72  ** overloaded or
2fc50 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
2fc60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
2fc70 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20  oses.)^.** ^The 
2fc80 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c  destructor is al
2fc90 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68  so invoked if th
2fca0 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  e call to.** sql
2fcb0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2fcc0 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e  tion_v2() fails.
2fcd0 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65  .** ^When the de
2fce0 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63  structor callbac
2fcf0 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70  k of the tenth p
2fd00 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f  arameter is invo
2fd10 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61  ked, it.** is pa
2fd20 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72  ssed a single ar
2fd30 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
2fd40 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70  a copy of the ap
2fd50 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a  plication data .
2fd60 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  ** pointer which
2fd70 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70   was the fifth p
2fd80 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2fd90 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2fda0 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  ion_v2()..**.** 
2fdb0 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64  ^It is permitted
2fdc0 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c   to register mul
2fdd0 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
2fde0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
2fdf0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77  e.** functions w
2fe00 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ith the same nam
2fe10 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65  e but with eithe
2fe20 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62  r differing numb
2fe30 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65  ers of.** argume
2fe40 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67  nts or differing
2fe50 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
2fe60 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c  encodings.  ^SQL
2fe70 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
2fe80 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
2fe90 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f  on that most clo
2fea0 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65  sely matches the
2feb0 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68   way in which th
2fec0 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  e.** SQL functio
2fed0 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66  n is used.  ^A f
2fee0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
2fef0 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f  tation with a no
2ff00 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41  n-negative.** nA
2ff10 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rg parameter is 
2ff20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74  a better match t
2ff30 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69  han a function i
2ff40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
2ff50 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65  th.** a negative
2ff60 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74   nArg.  ^A funct
2ff70 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72  ion where the pr
2ff80 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
2ff90 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73  oding.** matches
2ffa0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
2ffb0 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74  coding is a bett
2ffc0 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e  er.** match than
2ffd0 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
2ffe0 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69  e the encoding i
2fff0 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a  s different.  .*
30000 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68  * ^A function wh
30010 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
30020 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62   difference is b
30030 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61  etween UTF16le a
30040 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73  nd UTF16be.** is
30050 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20   a closer match 
30060 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
30070 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
30080 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
30090 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38  .** between UTF8
300a0 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a   and UTF16..**.*
300b0 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63  * ^Built-in func
300c0 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65  tions may be ove
300d0 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61  rloaded by new a
300e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
300f0 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a  ed functions..**
30100 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74  .** ^An applicat
30110 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
30120 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
30130 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a  d to call other.
30140 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
30150 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20  aces.  However, 
30160 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20  such calls must 
30170 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65  not.** close the
30180 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
30190 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a  tion nor finaliz
301a0 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70  e or reset the p
301b0 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
301c0 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68  ment in which th
301d0 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  e function is ru
301e0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71  nning..*/.int sq
301f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
30200 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ction(.  sqlite3
30210 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
30220 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
30230 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
30240 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
30250 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
30260 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
30270 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
30280 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
30290 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
302a0 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
302b0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
302c0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
302d0 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
302e0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
302f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
30300 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a  ate_function16(.
30310 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
30320 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75   const void *zFu
30330 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
30340 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
30350 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
30360 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
30370 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
30380 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
30390 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
303a0 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
303b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
303c0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
303d0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
303e0 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
303f0 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  text*).);.int sq
30400 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
30410 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ction_v2(.  sqli
30420 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
30430 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
30440 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
30450 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
30460 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
30470 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
30480 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
30490 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
304a0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
304b0 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
304c0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
304d0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
304e0 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
304f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
30500 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  ,.  void(*xDestr
30510 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  oy)(void*).);../
30520 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
30530 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a  ext Encodings.**
30540 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
30550 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65  nt define intege
30560 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70  r codes that rep
30570 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f  resent the vario
30580 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64  us.** text encod
30590 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62  ings supported b
305a0 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  y SQLite..*/.#de
305b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38  fine SQLITE_UTF8
305c0 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
305d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
305e0 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65  6LE        2.#de
305f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
30600 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65  6BE        3.#de
30610 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
30620 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20  6          4    
30630 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79  /* Use native by
30640 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66  te order */.#def
30650 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20  ine SQLITE_ANY  
30660 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f            5    /
30670 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
30680 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a  _function only *
30690 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
306a0 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20  _UTF16_ALIGNED  
306b0 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  8    /* sqlite3_
306c0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
306d0 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   only */../*.** 
306e0 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63  CAPI3REF: Deprec
306f0 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ated Functions.*
30700 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a  * DEPRECATED.**.
30710 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
30720 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74  ns are [deprecat
30730 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74  ed].  In order t
30740 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61  o maintain.** ba
30750 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
30760 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72  ility with older
30770 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e   code, these fun
30780 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
30790 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72  .** to be suppor
307a0 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e  ted.  However, n
307b0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
307c0 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20  should avoid.** 
307d0 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65  the use of these
307e0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20   functions.  To 
307f0 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70  help encourage p
30800 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a  eople to avoid.*
30810 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75  * using these fu
30820 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20  nctions, we are 
30830 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c  not going to tel
30840 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20  l you what they 
30850 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  do..*/.#ifndef S
30860 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45  QLITE_OMIT_DEPRE
30870 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50  CATED.SQLITE_DEP
30880 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
30890 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
308a0 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  unt(sqlite3_cont
308b0 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  ext*);.SQLITE_DE
308c0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
308d0 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c  ite3_expired(sql
308e0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c  ite3_stmt*);.SQL
308f0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
30900 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73  nt sqlite3_trans
30910 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  fer_bindings(sql
30920 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69  ite3_stmt*, sqli
30930 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
30940 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
30950 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c  t sqlite3_global
30960 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a  _recover(void);.
30970 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
30980 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74  D void sqlite3_t
30990 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f  hread_cleanup(vo
309a0 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  id);.SQLITE_DEPR
309b0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
309c0 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28  e3_memory_alarm(
309d0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
309e0 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29  lite3_int64,int)
309f0 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
30a00 20 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71          void*,sq
30a10 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65  lite3_int64);.#e
30a20 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
30a30 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20  3REF: Obtaining 
30a40 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72  SQL Function Par
30a50 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a  ameter Values.**
30a60 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61  .** The C-langua
30a70 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ge implementatio
30a80 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f  n of SQL functio
30a90 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
30aa0 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73  s uses.** this s
30ab0 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20  et of interface 
30ac0 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65  routines to acce
30ad0 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  ss the parameter
30ae0 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68   values on.** th
30af0 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  e function or ag
30b00 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54  gregate..**.** T
30b10 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63  he xFunc (for sc
30b20 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20  alar functions) 
30b30 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67  or xStep (for ag
30b40 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65  gregates) parame
30b50 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ters.** to [sqli
30b60 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
30b70 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
30b80 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
30b90 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69  ion16()].** defi
30ba0 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  ne callbacks tha
30bb0 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
30bc0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
30bd0 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a  d aggregates..**
30be0 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   The 3rd paramet
30bf0 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c  er to these call
30c00 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61  backs is an arra
30c10 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
30c20 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73  .** [protected s
30c30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
30c40 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73  jects.  There is
30c50 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   one [sqlite3_va
30c60 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a  lue] object for.
30c70 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65  ** each paramete
30c80 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e  r to the SQL fun
30c90 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f  ction.  These ro
30ca0 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
30cb0 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61  to.** extract va
30cc0 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73  lues from the [s
30cd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
30ce0 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  jects..**.** The
30cf0 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
30d00 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74   only with [prot
30d10 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
30d20 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
30d30 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
30d40 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  use these routin
30d50 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74  es on an [unprot
30d60 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
30d70 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  lue].** object r
30d80 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69  esults in undefi
30d90 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
30da0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
30db0 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69  nes work just li
30dc0 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  ke the correspon
30dd0 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63  ding [column acc
30de0 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a  ess functions].*
30df0 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74  * except that  t
30e00 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61  hese routines ta
30e10 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f  ke a single [pro
30e20 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
30e30 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20  alue] object.** 
30e40 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20  pointer instead 
30e50 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74  of a [sqlite3_st
30e60 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64  mt*] pointer and
30e70 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75   an integer colu
30e80 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a  mn number..**.**
30e90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
30ea0 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74  lue_text16() int
30eb0 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20  erface extracts 
30ec0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a  a UTF-16 string.
30ed0 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  ** in the native
30ee0 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74   byte-order of t
30ef0 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e  he host machine.
30f00 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
30f10 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
30f20 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
30f30 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20  alue_text16le() 
30f40 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78  interfaces.** ex
30f50 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72  tract UTF-16 str
30f60 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69  ings as big-endi
30f70 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e  an and little-en
30f80 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c  dian respectivel
30f90 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  y..**.** ^(The s
30fa0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
30fb0 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65  eric_type() inte
30fc0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
30fd0 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72  o apply.** numer
30fe0 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74  ic affinity to t
30ff0 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20  he value.  This 
31000 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74  means that an at
31010 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65  tempt is.** made
31020 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
31030 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65  value to an inte
31040 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20  ger or floating 
31050 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75  point.  If.** su
31060 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ch a conversion 
31070 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68  is possible with
31080 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f  out loss of info
31090 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65  rmation (in othe
310a0 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74  r.** words, if t
310b0 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74  he value is a st
310c0 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20  ring that looks 
310d0 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a  like a number).*
310e0 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65  * then the conve
310f0 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d  rsion is perform
31100 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e  ed.  Otherwise n
31110 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  o conversion occ
31120 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  urs..** The [SQL
31130 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
31140 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f  tatype] after co
31150 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75  nversion is retu
31160 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c  rned.)^.**.** Pl
31170 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75  ease pay particu
31180 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f  lar attention to
31190 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74   the fact that t
311a0 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72  he pointer retur
311b0 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
311c0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
311d0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
311e0 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a  ue_text()], or.*
311f0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
31200 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62  _text16()] can b
31210 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79  e invalidated by
31220 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61   a subsequent ca
31230 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
31240 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
31250 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
31260 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71  _bytes16()], [sq
31270 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
31280 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
31290 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
312a0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ()]..**.** These
312b0 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
312c0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
312d0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73  e same thread as
312e0 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
312f0 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69  tion that suppli
31300 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ed the [sqlite3_
31310 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65  value*] paramete
31320 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  rs..*/.const voi
31330 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
31340 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61  _blob(sqlite3_va
31350 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
31360 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73  e3_value_bytes(s
31370 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
31380 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
31390 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  e_bytes16(sqlite
313a0 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c  3_value*);.doubl
313b0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
313c0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76  double(sqlite3_v
313d0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
313e0 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71  te3_value_int(sq
313f0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73  lite3_value*);.s
31400 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
31410 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34  ite3_value_int64
31420 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
31430 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
31440 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76   char *sqlite3_v
31450 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65  alue_text(sqlite
31460 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
31470 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
31480 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69  alue_text16(sqli
31490 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
314a0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
314b0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
314c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
314d0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
314e0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
314f0 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6be(sqlite3_valu
31500 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
31510 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69  _value_type(sqli
31520 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
31530 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
31540 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69  umeric_type(sqli
31550 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a  te3_value*);../*
31560 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
31570 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46  tain Aggregate F
31580 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a  unction Context.
31590 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61  **.** Implementa
315a0 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61  tions of aggrega
315b0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  te SQL functions
315c0 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75   use this.** rou
315d0 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  tine to allocate
315e0 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72   memory for stor
315f0 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e  ing their state.
31600 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
31610 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74  t time the sqlit
31620 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
31630 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
31640 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20  e is called .** 
31650 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
31660 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
31670 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61  ion, SQLite.** a
31680 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65  llocates N of me
31690 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74  mory, zeroes out
316a0 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e   that memory, an
316b0 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
316c0 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65  ter.** to the ne
316d0 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65  w memory. ^On se
316e0 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
316f0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ent calls to.** 
31700 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
31710 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20  e_context() for 
31720 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
31730 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
31740 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d  ance,.** the sam
31750 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75  e buffer is retu
31760 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61  rned.  Sqlite3_a
31770 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
31780 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a  () is normally.*
31790 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f  * called once fo
317a0 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f  r each invocatio
317b0 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63  n of the xStep c
317c0 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e  allback and then
317d0 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d   one.** last tim
317e0 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61  e when the xFina
317f0 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  l callback is in
31800 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e  voked.  ^(When n
31810 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20  o rows match.** 
31820 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65  an aggregate que
31830 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20  ry, the xStep() 
31840 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  callback of the 
31850 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
31860 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  on.** implementa
31870 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61  tion is never ca
31880 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28  lled and xFinal(
31890 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63  ) is called exac
318a0 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20  tly once..** In 
318b0 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c  those cases, sql
318c0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
318d0 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62  ontext() might b
318e0 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65  e called for the
318f0 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66  .** first time f
31900 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61  rom within xFina
31910 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  l().)^.**.** ^Th
31920 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
31930 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
31940 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
31950 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
31960 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63  .** when first c
31970 61 6c 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65  alled if N is le
31980 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
31990 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61   to zero or if a
319a0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
319b0 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ate error occurs
319c0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d  ..**.** ^(The am
319d0 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c  ount of space al
319e0 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
319f0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
31a00 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20  text(C,N) is.** 
31a10 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68  determined by th
31a20 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  e N parameter on
31a30 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75   first successfu
31a40 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e  l call.  Changin
31a50 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  g the.** value o
31a60 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e  f N in subsequen
31a70 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call to sqlite
31a80 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
31a90 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20  ext() within.** 
31aa0 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
31ab0 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
31ac0 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65  ance will not re
31ad0 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a  size the memory.
31ae0 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e  ** allocation.)^
31af0 20 20 57 69 74 68 69 6e 20 74 68 65 20 78 46 69    Within the xFi
31b00 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74  nal callback, it
31b10 20 69 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f   is customary to
31b20 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63   set.** N=0 in c
31b30 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
31b40 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
31b50 74 28 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e  t(C,N) so that n
31b60 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20  o .** pointless 
31b70 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
31b80 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20  ns occur..**.** 
31b90 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69  ^SQLite automati
31ba0 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20  cally frees the 
31bb0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64  memory allocated
31bc0 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   by .** sqlite3_
31bd0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
31be0 74 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67  t() when the agg
31bf0 72 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e  regate query con
31c00 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  cludes..**.** Th
31c10 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
31c20 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79  r must be a copy
31c30 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
31c40 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51  te3_context | SQ
31c50 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65  L function conte
31c60 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20  xt] that is the 
31c70 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a  first parameter.
31c80 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20  ** to the xStep 
31c90 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
31ca0 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20  ck routine that 
31cb0 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61  implements the a
31cc0 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63  ggregate.** func
31cd0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
31ce0 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
31cf0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
31d00 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
31d10 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67  which.** the agg
31d20 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
31d30 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
31d40 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
31d50 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
31d60 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
31d70 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29  xt*, int nBytes)
31d80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31d90 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72  F: User Data For
31da0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
31db0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73   ^The sqlite3_us
31dc0 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66  er_data() interf
31dd0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
31de0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
31df0 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68  nter that was th
31e00 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61  e pUserData para
31e10 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70  meter (the 5th p
31e20 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20  arameter).** of 
31e30 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
31e40 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
31e50 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
31e60 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
31e70 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68  6()] routines th
31e80 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  at originally.**
31e90 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
31ea0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
31eb0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ned function..**
31ec0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
31ed0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
31ee0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
31ef0 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
31f00 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
31f10 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
31f20 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
31f30 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75  .void *sqlite3_u
31f40 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33  ser_data(sqlite3
31f50 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a  _context*);../*.
31f60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
31f70 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
31f80 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   For Functions.*
31f90 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
31fa0 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
31fb0 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  dle() interface 
31fc0 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
31fd0 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
31fe0 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73   to the [databas
31ff0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74  e connection] (t
32000 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
32010 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
32020 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
32030 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
32040 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
32050 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
32060 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
32070 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
32080 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
32090 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
320a0 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  tion..*/.sqlite3
320b0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   *sqlite3_contex
320c0 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69  t_db_handle(sqli
320d0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
320e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
320f0 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61  Function Auxilia
32100 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68  ry Data.**.** Th
32110 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  ese functions ma
32120 79 20 62 65 20 75 73 65 64 20 62 79 20 28 6e 6f  y be used by (no
32130 6e 2d 61 67 67 72 65 67 61 74 65 29 20 53 51 4c  n-aggregate) SQL
32140 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a   functions to.**
32150 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64   associate metad
32160 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e  ata with argumen
32170 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65  t values. If the
32180 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70   same value is p
32190 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74  assed to.** mult
321a0 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73  iple invocations
321b0 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c   of the same SQL
321c0 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67   function during
321d0 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e   query execution
321e0 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20  , under.** some 
321f0 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68  circumstances th
32200 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74  e associated met
32210 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65  adata may be pre
32220 73 65 72 76 65 64 2e 20 20 41 6e 20 65 78 61 6d  served.  An exam
32230 70 6c 65 0a 2a 2a 20 6f 66 20 77 68 65 72 65 20  ple.** of where 
32240 74 68 69 73 20 6d 69 67 68 74 20 62 65 20 75 73  this might be us
32250 65 66 75 6c 20 69 73 20 69 6e 20 61 20 72 65 67  eful is in a reg
32260 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20  ular-expression 
32270 6d 61 74 63 68 69 6e 67 0a 2a 2a 20 66 75 6e 63  matching.** func
32280 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c  tion. The compil
32290 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ed version of th
322a0 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
322b0 73 69 6f 6e 20 63 61 6e 20 62 65 20 73 74 6f 72  sion can be stor
322c0 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74  ed as.** metadat
322d0 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  a associated wit
322e0 68 20 74 68 65 20 70 61 74 74 65 72 6e 20 73 74  h the pattern st
322f0 72 69 6e 67 2e 20 20 0a 2a 2a 20 54 68 65 6e 20  ring.  .** Then 
32300 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 70  as long as the p
32310 61 74 74 65 72 6e 20 73 74 72 69 6e 67 20 72 65  attern string re
32320 6d 61 69 6e 73 20 74 68 65 20 73 61 6d 65 2c 0a  mains the same,.
32330 2a 2a 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20  ** the compiled 
32340 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
32350 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64  on can be reused
32360 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20   on multiple.** 
32370 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
32380 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
32390 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
323a0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
323b0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
323c0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
323d0 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a  o the metadata.*
323e0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20  * associated by 
323f0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
32400 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69  auxdata() functi
32410 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20  on with the Nth 
32420 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75  argument.** valu
32430 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  e to the applica
32440 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
32450 63 74 69 6f 6e 2e 20 5e 49 66 20 74 68 65 72 65  ction. ^If there
32460 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 0a   is no metadata.
32470 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
32480 74 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  th the function 
32490 61 72 67 75 6d 65 6e 74 2c 20 74 68 69 73 20 73  argument, this s
324a0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
324b0 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  ta() interface.*
324c0 2a 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  * returns a NULL
324d0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
324e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74  ^The sqlite3_set
324f0 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58  _auxdata(C,N,P,X
32500 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65  ) interface save
32510 73 20 50 20 61 73 20 6d 65 74 61 64 61 74 61 20  s P as metadata 
32520 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20  for the N-th.** 
32530 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
32540 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
32550 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e  ned function.  ^
32560 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  Subsequent.** ca
32570 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67  lls to sqlite3_g
32580 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 20  et_auxdata(C,N) 
32590 72 65 74 75 72 6e 20 50 20 66 72 6f 6d 20 74 68  return P from th
325a0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a  e most recent.**
325b0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
325c0 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 63 61  data(C,N,P,X) ca
325d0 6c 6c 20 69 66 20 74 68 65 20 6d 65 74 61 64 61  ll if the metada
325e0 74 61 20 69 73 20 73 74 69 6c 6c 20 76 61 6c 69  ta is still vali
325f0 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20  d or.** NULL if 
32600 74 68 65 20 6d 65 74 61 64 61 74 61 20 68 61 73  the metadata has
32610 20 62 65 65 6e 20 64 69 73 63 61 72 64 65 64 2e   been discarded.
32620 0a 2a 2a 20 5e 41 66 74 65 72 20 65 61 63 68 20  .** ^After each 
32630 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
32640 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
32650 50 2c 58 29 20 77 68 65 72 65 20 58 20 69 73 20  P,X) where X is 
32660 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c  not NULL,.** SQL
32670 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  ite will invoke 
32680 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 66  the destructor f
32690 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 20 70  unction X with p
326a0 61 72 61 6d 65 74 65 72 20 50 20 65 78 61 63 74  arameter P exact
326b0 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68 65 6e  ly.** once, when
326c0 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73   the metadata is
326d0 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 53   discarded..** S
326e0 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f  QLite is free to
326f0 20 64 69 73 63 61 72 64 20 74 68 65 20 6d 65 74   discard the met
32700 61 64 61 74 61 20 61 74 20 61 6e 79 20 74 69 6d  adata at any tim
32710 65 2c 20 69 6e 63 6c 75 64 69 6e 67 3a 20 3c 75  e, including: <u
32720 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20  l>.** <li> when 
32730 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
32740 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  g function param
32750 65 74 65 72 20 63 68 61 6e 67 65 73 2c 20 6f 72  eter changes, or
32760 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 5b 73  .** <li> when [s
32770 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
32780 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
32790 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  lize()] is calle
327a0 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20  d for the.**    
327b0 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c    SQL statement,
327c0 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e   or.** <li> when
327d0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
327e0 64 61 74 61 28 29 20 69 73 20 69 6e 76 6f 6b 65  data() is invoke
327f0 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 65 20 73  d again on the s
32800 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 6f  ame parameter, o
32810 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75 72 69 6e 67  r.** <li> during
32820 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 71   the original sq
32830 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
32840 61 28 29 20 63 61 6c 6c 20 77 68 65 6e 20 61 20  a() call when a 
32850 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20 20 20 20 20  memory .**      
32860 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
32870 20 6f 63 63 75 72 73 2e 20 3c 2f 75 6c 3e 29 5e   occurs. </ul>)^
32880 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 65 20  .**.** Note the 
32890 6c 61 73 74 20 62 75 6c 6c 65 74 20 69 6e 20 70  last bullet in p
328a0 61 72 74 69 63 75 6c 61 72 2e 20 20 54 68 65 20  articular.  The 
328b0 64 65 73 74 72 75 63 74 6f 72 20 58 20 69 6e 20  destructor X in 
328c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  .** sqlite3_set_
328d0 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29  auxdata(C,N,P,X)
328e0 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64   might be called
328f0 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
32900 66 6f 72 65 20 74 68 65 0a 2a 2a 20 73 71 6c 69  fore the.** sqli
32910 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
32920 29 20 69 6e 74 65 72 66 61 63 65 20 65 76 65 6e  ) interface even
32930 20 72 65 74 75 72 6e 73 2e 20 20 48 65 6e 63 65   returns.  Hence
32940 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
32950 64 61 74 61 28 29 0a 2a 2a 20 73 68 6f 75 6c 64  data().** should
32960 20 62 65 20 63 61 6c 6c 65 64 20 6e 65 61 72 20   be called near 
32970 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66  the end of the f
32980 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
32990 74 61 74 69 6f 6e 20 61 6e 64 20 74 68 65 0a 2a  tation and the.*
329a0 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  * function imple
329b0 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
329c0 20 6e 6f 74 20 6d 61 6b 65 20 61 6e 79 20 75 73   not make any us
329d0 65 20 6f 66 20 50 20 61 66 74 65 72 0a 2a 2a 20  e of P after.** 
329e0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
329f0 61 74 61 28 29 20 68 61 73 20 62 65 65 6e 20 63  ata() has been c
32a00 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  alled..**.** ^(I
32a10 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61  n practice, meta
32a20 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65  data is preserve
32a30 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69  d between functi
32a40 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20  on calls for.** 
32a50 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
32a60 65 72 73 20 74 68 61 74 20 61 72 65 20 63 6f 6d  ers that are com
32a70 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e 73 74 61  pile-time consta
32a80 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 6c  nts, including l
32a90 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73  iteral.** values
32aa0 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73   and [parameters
32ab0 5d 20 61 6e 64 20 65 78 70 72 65 73 73 69 6f 6e  ] and expression
32ac0 73 20 63 6f 6d 70 6f 73 65 64 20 66 72 6f 6d 20  s composed from 
32ad0 74 68 65 20 73 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a  the same.)^.**.*
32ae0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
32af0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
32b00 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
32b10 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
32b20 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
32b30 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
32b40 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67  .void *sqlite3_g
32b50 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
32b60 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
32b70 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65   N);.void sqlite
32b80 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_set_auxdata(sq
32b90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
32ba0 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f  int N, void*, vo
32bb0 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  id (*)(void*));.
32bc0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32bd0 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69  : Constants Defi
32be0 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73  ning Special Des
32bf0 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72  tructor Behavior
32c00 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65  .**.** These are
32c10 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20   special values 
32c20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74  for the destruct
32c30 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65  or that is passe
32c40 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66  d in as the.** f
32c50 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f  inal argument to
32c60 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
32c70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
32c80 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65  lob()].  ^If the
32c90 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61   destructor.** a
32ca0 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54  rgument is SQLIT
32cb0 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61  E_STATIC, it mea
32cc0 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
32cd0 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63  ent pointer is c
32ce0 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77  onstant.** and w
32cf0 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65  ill never change
32d00 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e  .  It does not n
32d10 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f  eed to be destro
32d20 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51  yed.  ^The.** SQ
32d30 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76  LITE_TRANSIENT v
32d40 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20  alue means that 
32d50 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c  the content will
32d60 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69   likely change i
32d70 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75  n.** the near fu
32d80 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51  ture and that SQ
32d90 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65  Lite should make
32da0 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
32db0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
32dc0 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72  content before r
32dd0 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
32de0 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e  The typedef is n
32df0 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b  ecessary to work
32e00 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73   around problems
32e10 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43   in certain.** C
32e20 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 0a 2a 2f  ++ compilers..*/
32e30 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
32e40 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
32e50 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b  or_type)(void*);
32e60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
32e70 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71  STATIC      ((sq
32e80 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
32e90 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65  _type)0).#define
32ea0 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
32eb0 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65  T   ((sqlite3_de
32ec0 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31  structor_type)-1
32ed0 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
32ee0 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52  F: Setting The R
32ef0 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20  esult Of An SQL 
32f00 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54  Function.**.** T
32f10 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
32f20 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46  e used by the xF
32f30 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  unc or xFinal ca
32f40 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20  llbacks that.** 
32f50 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75  implement SQL fu
32f60 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
32f70 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20  egates.  See.** 
32f80 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
32f90 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
32fa0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
32fb0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
32fc0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
32fd0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
32fe0 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
32ff0 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63  ns work very muc
33000 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61  h like the [para
33010 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66  meter binding] f
33020 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63  amily of.** func
33030 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69  tions used to bi
33040 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73  nd values to hos
33050 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20  t parameters in 
33060 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
33070 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f  nts..** Refer to
33080 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65   the [SQL parame
33090 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  ter] documentati
330a0 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  on for additiona
330b0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
330c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
330d0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20  3_result_blob() 
330e0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
330f0 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
33100 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
33110 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
33120 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42  n to be the BLOB
33130 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69   whose content i
33140 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20  s pointed.** to 
33150 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  by the second pa
33160 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63  rameter and whic
33170 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e  h is N bytes lon
33180 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  g where N is the
33190 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65  .** third parame
331a0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
331b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
331c0 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  eroblob() interf
331d0 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73  aces set the res
331e0 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
331f0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
33200 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
33210 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69   a BLOB containi
33220 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62  ng all zero.** b
33230 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73  ytes and N bytes
33240 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20   in size, where 
33250 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  N is the value o
33260 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  f the 2nd parame
33270 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
33280 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
33290 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  ouble() interfac
332a0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
332b0 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
332c0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
332d0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
332e0 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
332f0 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64   value specified
33300 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61  .** by its 2nd a
33310 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
33320 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
33330 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
33340 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
33350 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e  ror16() function
33360 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69  s.** cause the i
33370 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66  mplemented SQL f
33380 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77  unction to throw
33390 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a   an exception..*
333a0 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74  * ^SQLite uses t
333b0 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  he string pointe
333c0 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32  d to by the.** 2
333d0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
333e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
333f0 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65  rror() or sqlite
33400 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
33410 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78  ().** as the tex
33420 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65  t of an error me
33430 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20  ssage.  ^SQLite 
33440 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65  interprets the e
33450 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
33460 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
33470 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33480 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51  () as UTF-8. ^SQ
33490 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  Lite.** interpre
334a0 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72  ts the string fr
334b0 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  om sqlite3_resul
334c0 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55  t_error16() as U
334d0 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a  TF-16 in native.
334e0 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20  ** byte order.  
334f0 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
33500 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
33510 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
33520 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
33530 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
33540 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65   is negative the
33550 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61  n SQLite takes a
33560 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  s the error.** m
33570 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20  essage all text 
33580 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  up through the f
33590 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
335a0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
335b0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
335c0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
335d0 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20  t_error() or.** 
335e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
335f0 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d  rror16() is non-
33600 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
33610 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20  Lite takes that 
33620 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e  many.** bytes (n
33630 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66  ot characters) f
33640 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
33650 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72  meter as the err
33660 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e  or message..** ^
33670 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
33680 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
33690 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
336a0 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  ror16().** routi
336b0 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61  nes make a priva
336c0 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65  te copy of the e
336d0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78  rror message tex
336e0 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79  t before.** they
336f0 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c   return.  Hence,
33700 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   the calling fun
33710 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f  ction can deallo
33720 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66  cate or.** modif
33730 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72  y the text after
33740 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74   they return wit
33750 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54  hout harm..** ^T
33760 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
33770 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66  t_error_code() f
33780 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20  unction changes 
33790 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  the error code.*
337a0 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51  * returned by SQ
337b0 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74  Lite as a result
337c0 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20   of an error in 
337d0 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79  a function.  ^By
337e0 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65   default,.** the
337f0 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53   error code is S
33800 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41  QLITE_ERROR.  ^A
33810 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
33820 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
33830 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
33840 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33850 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73  error16() resets
33860 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
33870 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  to SQLITE_ERROR.
33880 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
33890 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
338a0 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66  _toobig() interf
338b0 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
338c0 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a  e to throw an.**
338d0 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e   error indicatin
338e0 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20  g that a string 
338f0 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c  or BLOB is too l
33900 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ong to represent
33910 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
33920 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
33930 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66  r_nomem() interf
33940 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
33950 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a  e to throw an.**
33960 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e   error indicatin
33970 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20  g that a memory 
33980 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65  allocation faile
33990 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
339a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
339b0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
339c0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
339d0 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
339e0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
339f0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
33a00 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65  the 32-bit signe
33a10 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
33a20 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
33a30 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
33a40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
33a50 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74  sult_int64() int
33a60 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
33a70 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
33a80 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
33a90 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
33aa0 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34  ion to be the 64
33ab0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
33ac0 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
33ad0 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
33ae0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
33af0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
33b00 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61  t_null() interfa
33b10 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
33b20 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
33b30 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
33b40 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
33b50 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  to be NULL..**.*
33b60 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
33b70 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71  esult_text(), sq
33b80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
33b90 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  t16(),.** sqlite
33ba0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
33bb0 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  e(), and sqlite3
33bc0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
33bd0 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
33be0 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20   set the return 
33bf0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70  value of the app
33c00 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
33c10 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a   function to be.
33c20 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67  ** a text string
33c30 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73   which is repres
33c40 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20  ented as UTF-8, 
33c50 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
33c60 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46  te order,.** UTF
33c70 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61  -16 little endia
33c80 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67  n, or UTF-16 big
33c90 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74   endian, respect
33ca0 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  ively..** ^SQLit
33cb0 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74  e takes the text
33cc0 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65   result from the
33cd0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f   application fro
33ce0 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72  m.** the 2nd par
33cf0 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71  ameter of the sq
33d00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
33d10 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  t* interfaces..*
33d20 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61  * ^If the 3rd pa
33d30 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
33d40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
33d50 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
33d60 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  * is negative, t
33d70 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
33d80 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f   result text fro
33d90 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
33da0 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74  ter.** through t
33db0 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
33dc0 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  aracter..** ^If 
33dd0 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
33de0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
33df0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
33e00 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e  terfaces.** is n
33e10 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
33e20 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20  n as many bytes 
33e30 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
33e40 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20   of the text.** 
33e50 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
33e60 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
33e70 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65  are taken as the
33e80 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
33e90 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ined.** function
33ea0 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68 65   result.  If the
33eb0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69   3rd parameter i
33ec0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
33ed0 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20  then it.** must 
33ee0 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73  be the byte offs
33ef0 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72 69  et into the stri
33f00 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c  ng where the NUL
33f10 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c   terminator woul
33f20 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20 74  d.** appear if t
33f30 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20  he string where 
33f40 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  NUL terminated. 
33f50 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72   If any NUL char
33f60 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20  acters occur.** 
33f70 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61 74  in the string at
33f80 20 61 20 62 79 74 65 20 6f 66 66 73 65 74 20 74   a byte offset t
33f90 68 61 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  hat is less than
33fa0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
33fb0 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  e 3rd.** paramet
33fc0 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  er, then the res
33fd0 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77 69  ulting string wi
33fe0 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64  ll contain embed
33ff0 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68 65  ded NULs and the
34000 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65 78  .** result of ex
34010 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61 74  pressions operat
34020 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20 77  ing on strings w
34030 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ith embedded NUL
34040 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s is undefined..
34050 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
34060 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
34070 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
34080 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
34090 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
340a0 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e  sult_blob is a n
340b0 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
340c0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c   then SQLite cal
340d0 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74  ls that.** funct
340e0 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72  ion as the destr
340f0 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78  uctor on the tex
34100 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74  t or BLOB result
34110 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20   when it has.** 
34120 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
34130 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  hat result..** ^
34140 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
34150 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
34160 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
34170 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74   interfaces or t
34180 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  o.** sqlite3_res
34190 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20  ult_blob is the 
341a0 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74  special constant
341b0 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
341c0 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61  then SQLite.** a
341d0 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20  ssumes that the 
341e0 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
341f0 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61  ult is in consta
34200 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  nt space and doe
34210 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68  s not.** copy th
34220 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
34230 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63   parameter nor c
34240 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72  all a destructor
34250 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a   on the content.
34260 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66  ** when it has f
34270 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
34280 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49  at result..** ^I
34290 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
342a0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
342b0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
342c0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
342d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
342e0 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
342f0 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
34300 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a  ITE_TRANSIENT.**
34310 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b   then SQLite mak
34320 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
34330 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61   result into spa
34340 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ce obtained from
34350 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
34360 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f  3_malloc()] befo
34370 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a  re it returns..*
34380 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
34390 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
343a0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
343b0 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a  the result of.**
343c0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
343d0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
343e0 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74  n to be a copy t
343f0 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  he.** [unprotect
34400 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
34410 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69  ] object specifi
34420 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61  ed by the 2nd pa
34430 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a  rameter.  ^The.*
34440 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
34450 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
34460 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  ce makes a copy 
34470 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
34480 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61  value].** so tha
34490 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  t the [sqlite3_v
344a0 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20  alue] specified 
344b0 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
344c0 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a   may change or.*
344d0 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  * be deallocated
344e0 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72   after sqlite3_r
344f0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65  esult_value() re
34500 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61  turns without ha
34510 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65  rm..** ^A [prote
34520 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
34530 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61  ue] object may a
34540 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68  lways be used wh
34550 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f  ere an.** [unpro
34560 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
34570 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20  alue] object is 
34580 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74  required, so eit
34590 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b  her.** kind of [
345a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
345b0 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65  bject can be use
345c0 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65  d with this inte
345d0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  rface..**.** If 
345e0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
345f0 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77  re called from w
34600 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72  ithin the differ
34610 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68  ent thread.** th
34620 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61  an the one conta
34630 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63  ining the applic
34640 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
34650 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65  nction that rece
34660 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  ived.** the [sql
34670 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f  ite3_context] po
34680 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c  inter, the resul
34690 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
346a0 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
346b0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71  3_result_blob(sq
346c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
346d0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
346e0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
346f0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
34700 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71  result_double(sq
34710 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
34720 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71  double);.void sq
34730 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
34740 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  or(sqlite3_conte
34750 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
34760 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
34770 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
34780 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  r16(sqlite3_cont
34790 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
347a0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
347b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
347c0 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65  or_toobig(sqlite
347d0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
347e0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
347f0 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c  _error_nomem(sql
34800 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
34810 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
34820 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73  ult_error_code(s
34830 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
34840 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
34850 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73  te3_result_int(s
34860 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
34870 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
34880 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
34890 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
348a0 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
348b0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
348c0 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69  result_null(sqli
348d0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
348e0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
348f0 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  lt_text(sqlite3_
34900 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
34910 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  char*, int, void
34920 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
34930 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
34940 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
34950 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
34960 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
34970 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
34980 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
34990 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
349a0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
349b0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
349c0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
349d0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
349e0 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  t_text16be(sqlit
349f0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
34a00 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
34a10 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
34a20 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
34a30 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  lt_value(sqlite3
34a40 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
34a50 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64  e3_value*);.void
34a60 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34a70 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
34a80 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
34a90 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
34aa0 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43  EF: Define New C
34ab0 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63  ollating Sequenc
34ac0 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  es.**.** ^These 
34ad0 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72  functions add, r
34ae0 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79  emove, or modify
34af0 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61   a [collation] a
34b00 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74  ssociated.** wit
34b10 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
34b20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
34b30 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72  ified as the fir
34b40 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
34b50 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
34b60 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73  the collation is
34b70 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a   a UTF-8 string.
34b80 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ** for sqlite3_c
34b90 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
34ba0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72  ) and sqlite3_cr
34bb0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
34bc0 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46  2().** and a UTF
34bd0 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
34be0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
34bf0 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
34c00 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
34c10 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20  ..** ^Collation 
34c20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61  names that compa
34c30 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69  re equal accordi
34c40 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ng to [sqlite3_s
34c50 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a  trnicmp()] are.*
34c60 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20  * considered to 
34c70 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  be the same name
34c80 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68  ..**.** ^(The th
34c90 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54  ird argument (eT
34ca0 65 78 74 52 65 70 29 20 6d 75 73 74 20 62 65 20  extRep) must be 
34cb0 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74  one of the const
34cc0 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ants:.** <ul>.**
34cd0 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
34ce0 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  F8],.** <li> [SQ
34cf0 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a  LITE_UTF16LE],.*
34d00 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
34d10 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  TF16BE],.** <li>
34d20 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c   [SQLITE_UTF16],
34d30 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
34d40 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
34d50 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  D]..** </ul>)^.*
34d60 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65 70 20  * ^The eTextRep 
34d70 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69  argument determi
34d80 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  nes the encoding
34d90 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73 73   of strings pass
34da0 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c  ed.** to the col
34db0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
34dc0 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62  callback, xCallb
34dd0 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ack..** ^The [SQ
34de0 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20  LITE_UTF16] and 
34df0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c  [SQLITE_UTF16_AL
34e00 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f  IGNED] values fo
34e10 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f  r eTextRep.** fo
34e20 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62  rce strings to b
34e30 65 20 55 54 46 31 36 20 77 69 74 68 20 6e 61 74  e UTF16 with nat
34e40 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
34e50 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
34e60 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76  UTF16_ALIGNED] v
34e70 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52 65  alue for eTextRe
34e80 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73  p forces strings
34e90 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20   to begin.** on 
34ea0 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64 64  an even byte add
34eb0 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ress..**.** ^The
34ec0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
34ed0 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70  , pArg, is an ap
34ee0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
34ef0 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70  ointer that is p
34f00 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68  assed.** through
34f10 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
34f20 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f  gument to the co
34f30 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
34f40 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
34f50 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
34f60 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c  ment, xCallback,
34f70 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
34f80 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
34f90 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c  unction..** ^Mul
34fa0 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20  tiple collating 
34fb0 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65  functions can be
34fc0 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e   registered usin
34fd0 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  g the same name 
34fe0 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66  but.** with diff
34ff0 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 70  erent eTextRep p
35000 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51  arameters and SQ
35010 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68  Lite will use wh
35020 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74  ichever.** funct
35030 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68 65  ion requires the
35040 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
35050 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61   data transforma
35060 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  tion..** ^If the
35070 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d   xCallback argum
35080 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  ent is NULL then
35090 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
350a0 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65  unction is.** de
350b0 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c  leted.  ^When al
350c0 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  l collating func
350d0 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65  tions having the
350e0 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64   same name are d
350f0 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20  eleted,.** that 
35100 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20  collation is no 
35110 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a  longer usable..*
35120 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74  *.** ^The collat
35130 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  ing function cal
35140 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
35150 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20   with a copy of 
35160 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70  the pArg .** app
35170 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
35180 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20 74  inter and with t
35190 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68  wo strings in th
351a0 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69  e encoding speci
351b0 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65  fied.** by the e
351c0 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74  TextRep argument
351d0 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67  .  The collating
351e0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72   function must r
351f0 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65  eturn an.** inte
35200 67 65 72 20 74 68 61 74 20 69 73 20 6e 65 67 61  ger that is nega
35210 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70  tive, zero, or p
35220 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68  ositive.** if th
35230 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69  e first string i
35240 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75  s less than, equ
35250 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65  al to, or greate
35260 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e  r than the secon
35270 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  d,.** respective
35280 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67  ly.  A collating
35290 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61   function must a
352a0 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65  lways return the
352b0 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20   same answer.** 
352c0 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69  given the same i
352d0 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f  nputs.  If two o
352e0 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67  r more collating
352f0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72   functions are r
35300 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20  egistered.** to 
35310 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69  the same collati
35320 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64  on name (using d
35330 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65  ifferent eTextRe
35340 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61  p values) then a
35350 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20  ll.** must give 
35360 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e  an equivalent an
35370 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65  swer when invoke
35380 64 20 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e  d with equivalen
35390 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68  t strings..** Th
353a0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
353b0 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74  tion must obey t
353c0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f  he following pro
353d0 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a  perties for all.
353e0 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c  ** strings A, B,
353f0 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f   and C:.**.** <o
35400 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d  l>.** <li> If A=
35410 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a  =B then B==A..**
35420 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e   <li> If A==B an
35430 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43  d B==C then A==C
35440 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c  ..** <li> If A&l
35450 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e  t;B THEN B&gt;A.
35460 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74  .** <li> If A&lt
35470 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68  ;B and B&lt;C th
35480 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f  en A&lt;C..** </
35490 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63  ol>.**.** If a c
354a0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
354b0 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74  n fails any of t
354c0 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61  he above constra
354d0 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a  ints and that.**
354e0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
354f0 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65 72  ion is  register
35500 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65  ed and used, the
35510 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
35520 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75  f SQLite.** is u
35530 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
35540 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65  ^The sqlite3_cre
35550 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
35560 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  () works like sq
35570 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
35580 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68  lation().** with
35590 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68   the addition th
355a0 61 74 20 74 68 65 20 78 44 65 73 74 72 6f 79 20  at the xDestroy 
355b0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
355c0 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e  ked on pArg when
355d0 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e  .** the collatin
355e0 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65  g function is de
355f0 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61  leted..** ^Colla
35600 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61  ting functions a
35610 72 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  re deleted when 
35620 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64  they are overrid
35630 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20  den by later.** 
35640 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c  calls to the col
35650 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  lation creation 
35660 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65  functions or whe
35670 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  n the.** [databa
35680 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
35690 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b  s closed using [
356a0 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
356b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65  ..**.** ^The xDe
356c0 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69  stroy callback i
356d0 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c  s <u>not</u> cal
356e0 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73  led if the .** s
356f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
35700 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e  llation_v2() fun
35710 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70  ction fails.  Ap
35720 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
35730 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
35740 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
35750 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e  on_v2() with a n
35760 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79  on-NULL xDestroy
35770 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
35780 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72   .** check the r
35790 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64  eturn code and d
357a0 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70  ispose of the ap
357b0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
357c0 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65  ointer.** themse
357d0 6c 76 65 73 20 72 61 74 68 65 72 20 74 68 61 6e  lves rather than
357e0 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74   expecting SQLit
357f0 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69  e to deal with i
35800 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54  t for them..** T
35810 68 69 73 20 69 73 20 64 69 66 66 65 72 65 6e 74  his is different
35820 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65   from every othe
35830 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
35840 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69  ce.  The inconsi
35850 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e  stency .** is un
35860 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63 61  fortunate but ca
35870 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20  nnot be changed 
35880 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
35890 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63   backwards .** c
358a0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
358b0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b  .** See also:  [
358c0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
358d0 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20  n_needed()] and 
358e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
358f0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a  on_needed16()]..
35900 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
35910 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
35920 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
35930 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
35940 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
35950 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72  ep, .  void *pAr
35960 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  g,.  int(*xCompa
35970 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
35980 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
35990 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  nst void*).);.in
359a0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
359b0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20  _collation_v2(. 
359c0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
359d0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
359e0 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
359f0 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c  , .  void *pArg,
35a00 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
35a10 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
35a20 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
35a30 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64  t void*),.  void
35a40 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
35a50 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
35a60 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
35a70 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  on16(.  sqlite3*
35a80 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  , .  const void 
35a90 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54  *zName,.  int eT
35aa0 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20  extRep, .  void 
35ab0 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43  *pArg,.  int(*xC
35ac0 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
35ad0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
35ae0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  t,const void*).)
35af0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
35b00 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65  F: Collation Nee
35b10 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ded Callbacks.**
35b20 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61  .** ^To avoid ha
35b30 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72  ving to register
35b40 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   all collation s
35b50 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20  equences before 
35b60 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61  a database.** ca
35b70 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e  n be used, a sin
35b80 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  gle callback fun
35b90 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67  ction may be reg
35ba0 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65  istered with the
35bb0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
35bc0 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20  nnection] to be 
35bd0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
35be0 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   an undefined co
35bf0 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
35c00 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64 2e  nce is required.
35c10 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
35c20 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73  unction is regis
35c30 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  tered using the 
35c40 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
35c50 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a  n_needed() API,.
35c60 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61  ** then it is pa
35c70 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f  ssed the names o
35c80 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  f undefined coll
35c90 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
35ca0 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e  as strings.** en
35cb0 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20  coded in UTF-8. 
35cc0 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  ^If sqlite3_coll
35cd0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
35ce0 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65   is used,.** the
35cf0 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65   names are passe
35d00 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d  d as UTF-16 in m
35d10 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79  achine native by
35d20 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20  te order..** ^A 
35d30 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66  call to either f
35d40 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73  unction replaces
35d50 20 74 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f   the existing co
35d60 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63  llation-needed c
35d70 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
35d80 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61  (When the callba
35d90 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74  ck is invoked, t
35da0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
35db0 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f  t passed is a co
35dc0 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63  py.** of the sec
35dd0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
35de0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
35df0 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a  n_needed() or.**
35e00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
35e10 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20  on_needed16().  
35e20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
35e30 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62  ent is the datab
35e40 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
35e50 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72  n.  The third ar
35e60 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
35e70 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20   [SQLITE_UTF8], 
35e80 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
35e90 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
35ea0 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61  UTF16LE], indica
35eb0 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65  ting the most de
35ec0 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20  sirable form of 
35ed0 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  the collation.**
35ee0 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69   sequence functi
35ef0 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68  on required.  Th
35f00 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
35f10 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
35f20 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65  f the.** require
35f30 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
35f40 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  ence.)^.**.** Th
35f50 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
35f60 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73  ion should regis
35f70 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20  ter the desired 
35f80 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a  collation using.
35f90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
35fa0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c  te_collation()],
35fb0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
35fc0 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c  _collation16()],
35fd0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
35fe0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
35ff0 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  _v2()]..*/.int s
36000 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
36010 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74  _needed(.  sqlit
36020 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a  e3*, .  void*, .
36030 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
36040 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
36050 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72  xtRep,const char
36060 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
36070 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
36080 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  ed16(.  sqlite3*
36090 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f  , .  void*,.  vo
360a0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
360b0 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
360c0 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  p,const void*).)
360d0 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  ;..#ifdef SQLITE
360e0 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a  _HAS_CODEC./*.**
360f0 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79   Specify the key
36100 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65   for an encrypte
36110 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69  d database.  Thi
36120 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64  s routine should
36130 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69   be.** called ri
36140 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65  ght after sqlite
36150 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_open()..**.** 
36160 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
36170 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
36180 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
36190 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
361a0 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
361b0 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
361c0 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  e3_key(.  sqlite
361d0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
361e0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
361f0 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
36200 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
36210 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
36220 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65  ey     /* The ke
36230 79 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  y */.);.int sqli
36240 74 65 33 5f 6b 65 79 5f 76 32 28 0a 20 20 73 71  te3_key_v2(.  sq
36250 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
36260 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
36270 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
36280 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
36290 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c  t char *zDbName,
362a0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61             /* Na
362b0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
362c0 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  se */.  const vo
362d0 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
362e0 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65  ey     /* The ke
362f0 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y */.);../*.** C
36300 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e  hange the key on
36310 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
36320 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65  e.  If the curre
36330 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e  nt database is n
36340 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c  ot.** encrypted,
36350 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
36360 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20  ll encrypt it.  
36370 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e  If pNew==0 or nN
36380 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61  ew==0, the.** da
36390 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70  tabase is decryp
363a0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ted..**.** The c
363b0 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
363c0 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
363d0 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
363e0 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
363f0 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
36400 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
36410 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
36420 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
36430 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
36440 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
36450 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
36460 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
36470 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b      /* The new k
36480 65 79 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ey */.);.int sql
36490 69 74 65 33 5f 72 65 6b 65 79 5f 76 32 28 0a 20  ite3_rekey_v2(. 
364a0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
364b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
364c0 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
364d0 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
364e0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61  onst char *zDbNa
364f0 6d 65 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a  me,           /*
36500 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   Name of the dat
36510 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
36520 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
36530 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
36540 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   new key */.);..
36550 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68  /*.** Specify th
36560 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79  e activation key
36570 20 66 6f 72 20 61 20 53 45 45 20 64 61 74 61 62   for a SEE datab
36580 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a  ase.  Unless .**
36590 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65   activated, none
365a0 20 6f 66 20 74 68 65 20 53 45 45 20 72 6f 75 74   of the SEE rout
365b0 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a  ines will work..
365c0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
365d0 61 63 74 69 76 61 74 65 5f 73 65 65 28 0a 20 20  activate_see(.  
365e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73  const char *zPas
365f0 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f  sPhrase        /
36600 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72  * Activation phr
36610 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66  ase */.);.#endif
36620 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  ..#ifdef SQLITE_
36630 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a  ENABLE_CEROD./*.
36640 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61  ** Specify the a
36650 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f  ctivation key fo
36660 72 20 61 20 43 45 52 4f 44 20 64 61 74 61 62 61  r a CEROD databa
36670 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20  se.  Unless .** 
36680 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20  activated, none 
36690 6f 66 20 74 68 65 20 43 45 52 4f 44 20 72 6f 75  of the CEROD rou
366a0 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e  tines will work.
366b0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
366c0 5f 61 63 74 69 76 61 74 65 5f 63 65 72 6f 64 28  _activate_cerod(
366d0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
366e0 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20  PassPhrase      
366f0 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20    /* Activation 
36700 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e  phrase */.);.#en
36710 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
36720 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65  REF: Suspend Exe
36730 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f  cution For A Sho
36740 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68  rt Time.**.** Th
36750 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28  e sqlite3_sleep(
36760 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65  ) function cause
36770 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68  s the current th
36780 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20  read to suspend 
36790 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72  execution.** for
367a0 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62   at least a numb
367b0 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
367c0 64 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20  ds specified in 
367d0 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  its parameter..*
367e0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72  *.** If the oper
367f0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65  ating system doe
36800 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c  s not support sl
36810 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74  eep requests wit
36820 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  h.** millisecond
36830 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e   time resolution
36840 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20  , then the time 
36850 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20  will be rounded 
36860 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61  up to.** the nea
36870 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65  rest second. The
36880 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69   number of milli
36890 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
368a0 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71   actually.** req
368b0 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20  uested from the 
368c0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
368d0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
368e0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c  .** ^SQLite impl
368f0 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65  ements this inte
36900 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67  rface by calling
36910 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a   the xSleep().**
36920 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64   method of the d
36930 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
36940 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 49 66  vfs] object.  If
36950 20 74 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65   the xSleep() me
36960 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 64  thod.** of the d
36970 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 6e 6f  efault VFS is no
36980 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 63 6f  t implemented co
36990 72 72 65 63 74 6c 79 2c 20 6f 72 20 6e 6f 74 20  rrectly, or not 
369a0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 74 0a 2a  implemented at.*
369b0 2a 20 61 6c 6c 2c 20 74 68 65 6e 20 74 68 65 20  * all, then the 
369c0 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
369d0 74 65 33 5f 73 6c 65 65 70 28 29 20 6d 61 79 20  te3_sleep() may 
369e0 64 65 76 69 61 74 65 20 66 72 6f 6d 20 74 68 65  deviate from the
369f0 20 64 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20   description.** 
36a00 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
36a10 70 61 72 61 67 72 61 70 68 73 2e 0a 2a 2f 0a 69  paragraphs..*/.i
36a20 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  nt sqlite3_sleep
36a30 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
36a40 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
36a50 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69  The Folder Holdi
36a60 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c  ng Temporary Fil
36a70 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68  es.**.** ^(If th
36a80 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  is global variab
36a90 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  le is made to po
36aa0 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20  int to a string 
36ab0 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20  which is.** the 
36ac0 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72  name of a folder
36ad0 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f   (a.k.a. directo
36ae0 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65  ry), then all te
36af0 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a  mporary files.**
36b00 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c 69   created by SQLi
36b10 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20  te when using a 
36b20 62 75 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65  built-in [sqlite
36b30 33 5f 76 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20  3_vfs | VFS].** 
36b40 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69  will be placed i
36b50 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f 72 79  n that directory
36b60 2e 29 5e 20 20 5e 49 66 20 74 68 69 73 20 76 61  .)^  ^If this va
36b70 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e  riable.** is a N
36b80 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
36b90 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d  n SQLite perform
36ba0 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 61  s a search for a
36bb0 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a  n appropriate.**
36bc0 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20   temporary file 
36bd0 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a  directory..**.**
36be0 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
36bf0 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66  to read or modif
36c00 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  y this variable 
36c10 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  in more than one
36c20 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61 20  .** thread at a 
36c30 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74  time.  It is not
36c40 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72   safe to read or
36c50 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
36c60 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64  iable.** if a [d
36c70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36c80 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65  on] is being use
36c90 64 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  d at the same ti
36ca0 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61 74 65  me in a separate
36cb0 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49  .** thread..** I
36cc0 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68  t is intended th
36cd0 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
36ce0 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20   be set once.** 
36cf0 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65  as part of proce
36d00 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
36d10 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79  n and before any
36d20 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
36d30 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61  e.** routines ha
36d40 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61  ve been called a
36d50 6e 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72  nd that this var
36d60 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63  iable remain unc
36d70 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61  hanged.** therea
36d80 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  fter..**.** ^The
36d90 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
36da0 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d  ectory pragma] m
36db0 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  ay modify this v
36dc0 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73  ariable and caus
36dd0 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74  e.** it to point
36de0 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   to memory obtai
36df0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
36e00 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72  3_malloc].  ^Fur
36e10 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65  thermore,.** the
36e20 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
36e30 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61  ectory pragma] a
36e40 6c 77 61 79 73 20 61 73 73 75 6d 65 73 20 74 68  lways assumes th
36e50 61 74 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a  at any string.**
36e60 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
36e70 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73  ble points to is
36e80 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20   held in memory 
36e90 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a  obtained from .*
36ea0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
36eb0 63 5d 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d  c] and the pragm
36ec0 61 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f  a may attempt to
36ed0 20 66 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72   free that memor
36ee0 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  y.** using [sqli
36ef0 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65  te3_free]..** He
36f00 6e 63 65 2c 20 69 66 20 74 68 69 73 20 76 61 72  nce, if this var
36f10 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65  iable is modifie
36f20 64 20 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68  d directly, eith
36f30 65 72 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a  er it should be.
36f40 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20  ** made NULL or 
36f50 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
36f60 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
36f70 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
36f80 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73  alloc].** or els
36f90 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65  e the use of the
36fa0 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
36fb0 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73  ectory pragma] s
36fc0 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64  hould be avoided
36fd0 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20  ..**.** <b>Note 
36fe0 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69  to Windows Runti
36ff0 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54  me users:</b>  T
37000 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72  he temporary dir
37010 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73  ectory must be s
37020 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63  et.** prior to c
37030 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
37040 6f 70 65 6e 5d 20 6f 72 20 5b 73 71 6c 69 74 65  open] or [sqlite
37050 33 5f 6f 70 65 6e 5f 76 32 5d 2e 20 20 4f 74 68  3_open_v2].  Oth
37060 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a  erwise, various.
37070 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74  ** features that
37080 20 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65   require the use
37090 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69   of temporary fi
370a0 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 20 20 48  les may fail.  H
370b0 65 72 65 20 69 73 20 61 6e 0a 2a 2a 20 65 78 61  ere is an.** exa
370c0 6d 70 6c 65 20 6f 66 20 68 6f 77 20 74 6f 20 64  mple of how to d
370d0 6f 20 74 68 69 73 20 75 73 69 6e 67 20 43 2b 2b  o this using C++
370e0 20 77 69 74 68 20 74 68 65 20 57 69 6e 64 6f 77   with the Window
370f0 73 20 52 75 6e 74 69 6d 65 3a 0a 2a 2a 0a 2a 2a  s Runtime:.**.**
37100 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
37110 65 3e 0a 2a 2a 20 4c 50 43 57 53 54 52 20 7a 50  e>.** LPCWSTR zP
37120 61 74 68 20 3d 20 57 69 6e 64 6f 77 73 3a 3a 53  ath = Windows::S
37130 74 6f 72 61 67 65 3a 3a 41 70 70 6c 69 63 61 74  torage::Applicat
37140 69 6f 6e 44 61 74 61 3a 3a 43 75 72 72 65 6e 74  ionData::Current
37150 2d 3e 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20  ->.** &nbsp;    
37160 20 54 65 6d 70 6f 72 61 72 79 46 6f 6c 64 65 72   TemporaryFolder
37170 2d 3e 50 61 74 68 2d 3e 44 61 74 61 28 29 3b 0a  ->Path->Data();.
37180 2a 2a 20 63 68 61 72 20 7a 50 61 74 68 42 75 66  ** char zPathBuf
37190 26 23 39 31 3b 4d 41 58 5f 50 41 54 48 20 2b 20  &#91;MAX_PATH + 
371a0 31 26 23 39 33 3b 3b 0a 2a 2a 20 6d 65 6d 73 65  1&#93;;.** memse
371b0 74 28 7a 50 61 74 68 42 75 66 2c 20 30 2c 20 73  t(zPathBuf, 0, s
371c0 69 7a 65 6f 66 28 7a 50 61 74 68 42 75 66 29 29  izeof(zPathBuf))
371d0 3b 0a 2a 2a 20 57 69 64 65 43 68 61 72 54 6f 4d  ;.** WideCharToM
371e0 75 6c 74 69 42 79 74 65 28 43 50 5f 55 54 46 38  ultiByte(CP_UTF8
371f0 2c 20 30 2c 20 7a 50 61 74 68 2c 20 2d 31 2c 20  , 0, zPath, -1, 
37200 7a 50 61 74 68 42 75 66 2c 20 73 69 7a 65 6f 66  zPathBuf, sizeof
37210 28 7a 50 61 74 68 42 75 66 29 2c 0a 2a 2a 20 26  (zPathBuf),.** &
37220 6e 62 73 70 3b 20 20 20 20 20 4e 55 4c 4c 2c 20  nbsp;     NULL, 
37230 4e 55 4c 4c 29 3b 0a 2a 2a 20 73 71 6c 69 74 65  NULL);.** sqlite
37240 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79  3_temp_directory
37250 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
37260 74 66 28 22 25 73 22 2c 20 7a 50 61 74 68 42 75  tf("%s", zPathBu
37270 66 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  f);.** </pre></b
37280 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2f 0a 53 51  lockquote>.*/.SQ
37290 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72  LITE_EXTERN char
372a0 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64   *sqlite3_temp_d
372b0 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a  irectory;../*.**
372c0 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
372d0 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f  Of The Folder Ho
372e0 6c 64 69 6e 67 20 44 61 74 61 62 61 73 65 20 46  lding Database F
372f0 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  iles.**.** ^(If 
37300 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69  this global vari
37310 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20  able is made to 
37320 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
37330 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68  g which is.** th
37340 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64  e name of a fold
37350 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63  er (a.k.a. direc
37360 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20  tory), then all 
37370 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 0a 2a  database files.*
37380 2a 20 73 70 65 63 69 66 69 65 64 20 77 69 74 68  * specified with
37390 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68   a relative path
373a0 6e 61 6d 65 20 61 6e 64 20 63 72 65 61 74 65 64  name and created
373b0 20 6f 72 20 61 63 63 65 73 73 65 64 20 62 79 0a   or accessed by.
373c0 2a 2a 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75  ** SQLite when u
373d0 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20  sing a built-in 
373e0 77 69 6e 64 6f 77 73 20 5b 73 71 6c 69 74 65 33  windows [sqlite3
373f0 5f 76 66 73 20 7c 20 56 46 53 5d 20 77 69 6c 6c  _vfs | VFS] will
37400 20 62 65 20 61 73 73 75 6d 65 64 0a 2a 2a 20 74   be assumed.** t
37410 6f 20 62 65 20 72 65 6c 61 74 69 76 65 20 74 6f  o be relative to
37420 20 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e   that directory.
37430 29 5e 20 5e 49 66 20 74 68 69 73 20 76 61 72 69  )^ ^If this vari
37440 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 0a 2a  able is a NULL.*
37450 2a 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  * pointer, then 
37460 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
37470 68 61 74 20 61 6c 6c 20 64 61 74 61 62 61 73 65  hat all database
37480 20 66 69 6c 65 73 20 73 70 65 63 69 66 69 65 64   files specified
37490 0a 2a 2a 20 77 69 74 68 20 61 20 72 65 6c 61 74  .** with a relat
374a0 69 76 65 20 70 61 74 68 6e 61 6d 65 20 61 72 65  ive pathname are
374b0 20 72 65 6c 61 74 69 76 65 20 74 6f 20 74 68 65   relative to the
374c0 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
374d0 72 79 0a 2a 2a 20 66 6f 72 20 74 68 65 20 70 72  ry.** for the pr
374e0 6f 63 65 73 73 2e 20 20 4f 6e 6c 79 20 74 68 65  ocess.  Only the
374f0 20 77 69 6e 64 6f 77 73 20 56 46 53 20 6d 61 6b   windows VFS mak
37500 65 73 20 75 73 65 20 6f 66 20 74 68 69 73 20 67  es use of this g
37510 6c 6f 62 61 6c 0a 2a 2a 20 76 61 72 69 61 62 6c  lobal.** variabl
37520 65 3b 20 69 74 20 69 73 20 69 67 6e 6f 72 65 64  e; it is ignored
37530 20 62 79 20 74 68 65 20 75 6e 69 78 20 56 46 53   by the unix VFS
37540 2e 0a 2a 2a 0a 2a 2a 20 43 68 61 6e 67 69 6e 67  ..**.** Changing
37550 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
37560 69 73 20 76 61 72 69 61 62 6c 65 20 77 68 69 6c  is variable whil
37570 65 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  e a database con
37580 6e 65 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 6f 70  nection is.** op
37590 65 6e 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e  en can result in
375a0 20 61 20 63 6f 72 72 75 70 74 20 64 61 74 61 62   a corrupt datab
375b0 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73  ase..**.** It is
375c0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61   not safe to rea
375d0 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  d or modify this
375e0 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72   variable in mor
375f0 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68  e than one.** th
37600 72 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20  read at a time. 
37610 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
37620 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66  to read or modif
37630 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  y this variable.
37640 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73  ** if a [databas
37650 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
37660 20 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74   being used at t
37670 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20  he same time in 
37680 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68  a separate.** th
37690 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69  read..** It is i
376a0 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69  ntended that thi
376b0 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65  s variable be se
376c0 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72  t once.** as par
376d0 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69  t of process ini
376e0 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20  tialization and 
376f0 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74  before any SQLit
37700 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  e interface.** r
37710 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65  outines have bee
37720 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61  n called and tha
37730 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
37740 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64  remain unchanged
37750 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a  .** thereafter..
37760 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 64 61 74 61  **.** ^The [data
37770 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
37780 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64   pragma] may mod
37790 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
377a0 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69  e and cause.** i
377b0 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65  t to point to me
377c0 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
377d0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
377e0 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f  oc].  ^Furthermo
377f0 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 64 61 74 61  re,.** the [data
37800 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
37810 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20   pragma] always 
37820 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79  assumes that any
37830 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20   string.** that 
37840 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f  this variable po
37850 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20  ints to is held 
37860 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  in memory obtain
37870 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
37880 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64  ite3_malloc] and
37890 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20   the pragma may 
378a0 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20  attempt to free 
378b0 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75  that memory.** u
378c0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
378d0 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69  ee]..** Hence, i
378e0 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  f this variable 
378f0 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65  is modified dire
37900 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20  ctly, either it 
37910 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64  should be.** mad
37920 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74  e NULL or made t
37930 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
37940 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
37950 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
37960 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20  .** or else the 
37970 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61  use of the [data
37980 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
37990 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20   pragma] should 
379a0 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53  be avoided..*/.S
379b0 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61  QLITE_EXTERN cha
379c0 72 20 2a 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  r *sqlite3_data_
379d0 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a  directory;../*.*
379e0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74  * CAPI3REF: Test
379f0 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74   For Auto-Commit
37a00 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44   Mode.** KEYWORD
37a10 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d  S: {autocommit m
37a20 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ode}.**.** ^The 
37a30 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f  sqlite3_get_auto
37a40 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61  commit() interfa
37a50 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ce returns non-z
37a60 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69  ero or.** zero i
37a70 66 20 74 68 65 20 67 69 76 65 6e 20 64 61 74 61  f the given data
37a80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
37a90 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20  is or is not in 
37aa0 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c  autocommit mode,
37ab0 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
37ac0 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  .  ^Autocommit m
37ad0 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66  ode is on by def
37ae0 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f  ault..** ^Autoco
37af0 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73  mmit mode is dis
37b00 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49  abled by a [BEGI
37b10 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  N] statement..**
37b20 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   ^Autocommit mod
37b30 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20  e is re-enabled 
37b40 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72  by a [COMMIT] or
37b50 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a   [ROLLBACK]..**.
37b60 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69  ** If certain ki
37b70 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63  nds of errors oc
37b80 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65  cur on a stateme
37b90 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74  nt within a mult
37ba0 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  i-statement.** t
37bb0 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f  ransaction (erro
37bc0 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51  rs including [SQ
37bd0 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c  LITE_FULL], [SQL
37be0 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b  ITE_IOERR],.** [
37bf0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b  SQLITE_NOMEM], [
37c00 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e  SQLITE_BUSY], an
37c10 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  d [SQLITE_INTERR
37c20 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a  UPT]) then the.*
37c30 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69  * transaction mi
37c40 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ght be rolled ba
37c50 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
37c60 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20  .  The only way 
37c70 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77  to.** find out w
37c80 68 65 74 68 65 72 20 53 51 4c 69 74 65 20 61 75  hether SQLite au
37c90 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c  tomatically roll
37ca0 65 64 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ed back the tran
37cb0 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a  saction after.**
37cc0 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20   an error is to 
37cd0 75 73 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f  use this functio
37ce0 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74  n..**.** If anot
37cf0 68 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67  her thread chang
37d00 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69  es the autocommi
37d10 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20  t status of the 
37d20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
37d30 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69  ection while thi
37d40 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e  s routine is run
37d50 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72  ning, then the r
37d60 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69  eturn value.** i
37d70 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  s undefined..*/.
37d80 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
37d90 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74  autocommit(sqlit
37da0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
37db0 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20  I3REF: Find The 
37dc0 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20  Database Handle 
37dd0 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74  Of A Prepared St
37de0 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54  atement.**.** ^T
37df0 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  he sqlite3_db_ha
37e00 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72  ndle interface r
37e10 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61  eturns the [data
37e20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
37e30 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68   handle.** to wh
37e40 69 63 68 20 61 20 5b 70 72 65 70 61 72 65 64 20  ich a [prepared 
37e50 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e  statement] belon
37e60 67 73 2e 20 20 5e 54 68 65 20 5b 64 61 74 61 62  gs.  ^The [datab
37e70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
37e80 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
37e90 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
37ea0 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61   is the same [da
37eb0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37ec0 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 74  n].** that was t
37ed0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
37ee0 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  t.** to the [sql
37ef0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
37f00 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20  )] call (or its 
37f10 76 61 72 69 61 6e 74 73 29 20 74 68 61 74 20 77  variants) that w
37f20 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72  as used to.** cr
37f30 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  eate the stateme
37f40 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  nt in the first 
37f50 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65  place..*/.sqlite
37f60 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  3 *sqlite3_db_ha
37f70 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndle(sqlite3_stm
37f80 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
37f90 33 52 45 46 3a 20 52 65 74 75 72 6e 20 54 68 65  3REF: Return The
37fa0 20 46 69 6c 65 6e 61 6d 65 20 46 6f 72 20 41 20   Filename For A 
37fb0 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
37fc0 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
37fd0 71 6c 69 74 65 33 5f 64 62 5f 66 69 6c 65 6e 61  qlite3_db_filena
37fe0 6d 65 28 44 2c 4e 29 20 69 6e 74 65 72 66 61 63  me(D,N) interfac
37ff0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
38000 74 65 72 20 74 6f 20 61 20 66 69 6c 65 6e 61 6d  ter to a filenam
38010 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  e.** associated 
38020 77 69 74 68 20 64 61 74 61 62 61 73 65 20 4e 20  with database N 
38030 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  of connection D.
38040 20 20 5e 54 68 65 20 6d 61 69 6e 20 64 61 74 61    ^The main data
38050 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 68 61 73  base file.** has
38060 20 74 68 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22   the name "main"
38070 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  .  If there is n
38080 6f 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  o attached datab
38090 61 73 65 20 4e 20 6f 6e 20 74 68 65 20 64 61 74  ase N on the dat
380a0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
380b0 69 6f 6e 20 44 2c 20 6f 72 20 69 66 20 64 61 74  ion D, or if dat
380c0 61 62 61 73 65 20 4e 20 69 73 20 61 20 74 65 6d  abase N is a tem
380d0 70 6f 72 61 72 79 20 6f 72 20 69 6e 2d 6d 65 6d  porary or in-mem
380e0 6f 72 79 20 64 61 74 61 62 61 73 65 2c 20 74 68  ory database, th
380f0 65 6e 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  en.** a NULL poi
38100 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
38110 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 6c  ..**.** ^The fil
38120 65 6e 61 6d 65 20 72 65 74 75 72 6e 65 64 20 62  ename returned b
38130 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  y this function 
38140 69 73 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66  is the output of
38150 20 74 68 65 0a 2a 2a 20 78 46 75 6c 6c 50 61 74   the.** xFullPat
38160 68 6e 61 6d 65 20 6d 65 74 68 6f 64 20 6f 66 20  hname method of 
38170 74 68 65 20 5b 56 46 53 5d 2e 20 20 5e 49 6e 20  the [VFS].  ^In 
38180 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
38190 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 69 6c   filename.** wil
381a0 6c 20 62 65 20 61 6e 20 61 62 73 6f 6c 75 74 65  l be an absolute
381b0 20 70 61 74 68 6e 61 6d 65 2c 20 65 76 65 6e 20   pathname, even 
381c0 69 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  if the filename 
381d0 75 73 65 64 0a 2a 2a 20 74 6f 20 6f 70 65 6e 20  used.** to open 
381e0 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 69  the database ori
381f0 67 69 6e 61 6c 6c 79 20 77 61 73 20 61 20 55 52  ginally was a UR
38200 49 20 6f 72 20 72 65 6c 61 74 69 76 65 20 70 61  I or relative pa
38210 74 68 6e 61 6d 65 2e 0a 2a 2f 0a 63 6f 6e 73 74  thname..*/.const
38220 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 64   char *sqlite3_d
38230 62 5f 66 69 6c 65 6e 61 6d 65 28 73 71 6c 69 74  b_filename(sqlit
38240 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68  e3 *db, const ch
38250 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f  ar *zDbName);../
38260 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
38270 65 74 65 72 6d 69 6e 65 20 69 66 20 61 20 64 61  etermine if a da
38280 74 61 62 61 73 65 20 69 73 20 72 65 61 64 2d 6f  tabase is read-o
38290 6e 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nly.**.** ^The s
382a0 71 6c 69 74 65 33 5f 64 62 5f 72 65 61 64 6f 6e  qlite3_db_readon
382b0 6c 79 28 44 2c 4e 29 20 69 6e 74 65 72 66 61 63  ly(D,N) interfac
382c0 65 20 72 65 74 75 72 6e 73 20 31 20 69 66 20 74  e returns 1 if t
382d0 68 65 20 64 61 74 61 62 61 73 65 20 4e 0a 2a 2a  he database N.**
382e0 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44   of connection D
382f0 20 69 73 20 72 65 61 64 2d 6f 6e 6c 79 2c 20 30   is read-only, 0
38300 20 69 66 20 69 74 20 69 73 20 72 65 61 64 2f 77   if it is read/w
38310 72 69 74 65 2c 20 6f 72 20 2d 31 20 69 66 20 4e  rite, or -1 if N
38320 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 6e   is not.** the n
38330 61 6d 65 20 6f 66 20 61 20 64 61 74 61 62 61 73  ame of a databas
38340 65 20 6f 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e on connection 
38350 44 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  D..*/.int sqlite
38360 33 5f 64 62 5f 72 65 61 64 6f 6e 6c 79 28 73 71  3_db_readonly(sq
38370 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74  lite3 *db, const
38380 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b   char *zDbName);
38390 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
383a0 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20  : Find the next 
383b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
383c0 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69  nt.**.** ^This i
383d0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
383e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
383f0 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64  e next [prepared
38400 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65   statement] afte
38410 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63  r.** pStmt assoc
38420 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
38430 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
38440 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20 70  ion] pDb.  ^If p
38450 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20  Stmt is NULL.** 
38460 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66  then this interf
38470 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
38480 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 72  inter to the fir
38490 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  st prepared stat
384a0 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61  ement.** associa
384b0 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61 74  ted with the dat
384c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
384d0 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72   pDb.  ^If no pr
384e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
384f0 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 68  .** satisfies th
38500 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20  e conditions of 
38510 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74  this routine, it
38520 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a   returns NULL..*
38530 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 61  *.** The [databa
38540 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
38550 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61  ointer D in a ca
38560 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
38570 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 29  3_next_stmt(D,S)
38580 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f 20  ] must refer to 
38590 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  an open database
385a0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61  .** connection a
385b0 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72  nd in particular
385c0 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e   must not be a N
385d0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a  ULL pointer..*/.
385e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71  sqlite3_stmt *sq
385f0 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
38600 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71  sqlite3 *pDb, sq
38610 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
38620 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
38630 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20  REF: Commit And 
38640 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63  Rollback Notific
38650 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
38660 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
38670 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29  e3_commit_hook()
38680 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
38690 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a  ters a callback.
386a0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ** function to b
386b0 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
386c0 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  er a transaction
386d0 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f   is [COMMIT | co
386e0 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e  mmitted]..** ^An
386f0 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
38700 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
38710 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d  l to sqlite3_com
38720 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f  mit_hook().** fo
38730 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  r the same datab
38740 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
38750 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a  s overridden..**
38760 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f   ^The sqlite3_ro
38770 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e  llback_hook() in
38780 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
38790 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  s a callback.** 
387a0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69  function to be i
387b0 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
387c0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
387d0 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c   [ROLLBACK | rol
387e0 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41  led back]..** ^A
387f0 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
38800 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
38810 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f  ll to sqlite3_ro
38820 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a  llback_hook().**
38830