/ Hex Artifact Content
Login

Artifact 64a77f2822f1325b12050972003184f99b655a0f:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
23f0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2400: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2410: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
2420: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2430: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
2440: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
2450: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2460: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
2470: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2480: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2490: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
24a0: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
24b0: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
24c0: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
24d0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
24e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24f0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2500: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2510: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
2520: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
2530: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
2540: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
2550: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
2560: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
2570: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2580: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2590: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
25a0: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
25b0: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
25c0: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
25d0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
25e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25f0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2600: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2610: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
2620: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
2630: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
2640: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2650: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
2660: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
2670: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2680: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2690: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26a0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26b0: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
26c0: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
26d0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
26e0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
26f0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2700: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2710: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
2720: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
2730: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2740: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
2750: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2760: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
2770: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2780: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2790: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
27a0: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
27b0: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
27c0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
27e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
27f0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2800: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2810: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
2820: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2830: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2840: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2850: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2860: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2870: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2890: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
28a0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
28b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
28c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
28d0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
28e0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2900: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2910: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2920: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2930: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2940: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2950: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2960: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2970: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2980: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2990: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
29a0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
29b0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
29c0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
29d0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
29e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
29f0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2a00: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2a10: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2a20: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
2a30: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2a40: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2a50: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
2a60: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
2a70: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
2a80: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
2a90: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
2aa0: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
2ab0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2ac0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
2ad0: 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71  K] if.** the [sq
2ae0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73  lite3] object is
2af0: 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65   successfully de
2b00: 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20  stroyed and all 
2b10: 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65  associated.** re
2b20: 73 6f 75 72 63 65 73 20 61 72 65 20 64 65 61 6c  sources are deal
2b30: 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  located..**.** ^
2b40: 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
2b50: 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73  connection is as
2b60: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 75 6e  sociated with un
2b70: 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72  finalized prepar
2b80: 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73  ed.** statements
2b90: 20 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73   or unfinished s
2ba0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62  qlite3_backup ob
2bb0: 6a 65 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74  jects then sqlit
2bc0: 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69  e3_close().** wi
2bd0: 6c 6c 20 6c 65 61 76 65 20 74 68 65 20 64 61 74  ll leave the dat
2be0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2bf0: 20 6f 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e   open and return
2c00: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a   [SQLITE_BUSY]..
2c10: 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  ** ^If sqlite3_c
2c20: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c  lose_v2() is cal
2c30: 6c 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c  led with unfinal
2c40: 69 7a 65 64 20 70 72 65 70 61 72 65 64 20 73 74  ized prepared st
2c50: 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f  atements.** and/
2c60: 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71  or unfinished sq
2c70: 6c 69 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74  lite3_backups, t
2c80: 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
2c90: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f   connection beco
2ca0: 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62  mes.** an unusab
2cb0: 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63  le "zombie" whic
2cc0: 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  h will automatic
2cd0: 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61  ally be dealloca
2ce0: 74 65 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20  ted when the.** 
2cf0: 6c 61 73 74 20 70 72 65 70 61 72 65 64 20 73 74  last prepared st
2d00: 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c  atement is final
2d10: 69 7a 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74  ized or the last
2d20: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20   sqlite3_backup 
2d30: 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20  is.** finished. 
2d40: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f   The sqlite3_clo
2d50: 73 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  se_v2() interfac
2d60: 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f  e is intended fo
2d70: 72 20 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f  r use with.** ho
2d80: 73 74 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61  st languages tha
2d90: 74 20 61 72 65 20 67 61 72 62 61 67 65 20 63 6f  t are garbage co
2da0: 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65  llected, and whe
2db0: 72 65 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20  re the order in 
2dc0: 77 68 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63  which.** destruc
2dd0: 74 6f 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20  tors are called 
2de0: 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a  is arbitrary..**
2df0: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
2e00: 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33   should [sqlite3
2e10: 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
2e20: 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61  lize] all [prepa
2e30: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c  red statements],
2e40: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
2e50: 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d  b_close | close]
2e60: 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c   all [BLOB handl
2e70: 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  es], and .** [sq
2e80: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e  lite3_backup_fin
2e90: 69 73 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c  ish | finish] al
2ea0: 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  l [sqlite3_backu
2eb0: 70 5d 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63  p] objects assoc
2ec0: 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  iated.** with th
2ed0: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
2ee0: 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65  ct prior to atte
2ef0: 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20  mpting to close 
2f00: 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66  the object.  ^If
2f10: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  .** sqlite3_clos
2f20: 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  e_v2() is called
2f30: 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20   on a [database 
2f40: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
2f50: 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75   still has.** ou
2f60: 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61  tstanding [prepa
2f70: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c  red statements],
2f80: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c   [BLOB handles],
2f90: 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69   and/or.** [sqli
2fa0: 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65  te3_backup] obje
2fb0: 63 74 73 20 74 68 65 6e 20 69 74 20 72 65 74 75  cts then it retu
2fc0: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
2fd0: 61 6e 64 20 74 68 65 20 64 65 61 6c 6c 6f 63 61  and the dealloca
2fe0: 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75  tion.** of resou
2ff0: 72 63 65 73 20 69 73 20 64 65 66 65 72 72 65 64  rces is deferred
3000: 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70   until all [prep
3010: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
3020: 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d  , [BLOB handles]
3030: 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ,.** and [sqlite
3040: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
3050: 73 20 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72  s are also destr
3060: 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  oyed..**.** ^If 
3070: 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  an [sqlite3] obj
3080: 65 63 74 20 69 73 20 64 65 73 74 72 6f 79 65 64  ect is destroyed
3090: 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63   while a transac
30a0: 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a  tion is open,.**
30b0: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
30c0: 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
30d0: 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
30e0: 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d  *.** The C param
30f0: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
3100: 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b  _close(C)] and [
3110: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
3120: 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20  (C)].** must be 
3130: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a  either a NULL.**
3140: 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b   pointer or an [
3150: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
3160: 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64  pointer obtained
3170: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3180: 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
3190: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f  te3_open16()], o
31a0: 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
31b0: 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f  en_v2()], and no
31c0: 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f  t previously clo
31d0: 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  sed..** ^Calling
31e0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
31f0: 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73   or sqlite3_clos
3200: 65 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e 55  e_v2() with a NU
3210: 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72  LL pointer.** ar
3220: 67 75 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d  gument is a harm
3230: 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69  less no-op..*/.i
3240: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
3250: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69 6e 74 20  (sqlite3*);.int 
3260: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
3270: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
3280: 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20  ** The type for 
3290: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
32a0: 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ion..** This is 
32b0: 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65  legacy and depre
32c0: 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e  cated.  It is in
32d0: 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f  cluded for histo
32e0: 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69  rical.** compati
32f0: 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f  bility and is no
3300: 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f  t documented..*/
3310: 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73  .typedef int (*s
3320: 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29  qlite3_callback)
3330: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
3340: 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a  *, char**);../*.
3350: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65  ** CAPI3REF: One
3360: 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63  -Step Query Exec
3370: 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a  ution Interface.
3380: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
3390: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
33a0: 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65  ce is a convenie
33b0: 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f 75  nce wrapper arou
33c0: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  nd.** [sqlite3_p
33d0: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73  repare_v2()], [s
33e0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
33f0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  and [sqlite3_fin
3400: 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61  alize()],.** tha
3410: 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c  t allows an appl
3420: 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d  ication to run m
3430: 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65 6e  ultiple statemen
3440: 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74  ts of SQL.** wit
3450: 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20 75  hout having to u
3460: 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f  se a lot of C co
3470: 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de. .**.** ^The 
3480: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3490: 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a 65  nterface runs ze
34a0: 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38  ro or more UTF-8
34b0: 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d   encoded,.** sem
34c0: 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20  icolon-separate 
34d0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70  SQL statements p
34e0: 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20 32  assed into its 2
34f0: 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20  nd argument,.** 
3500: 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f  in the context o
3510: 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
3520: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73  connection] pass
3530: 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 73 74  ed in as its 1st
3540: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e  .** argument.  ^
3550: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
3560: 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65 20  function of the 
3570: 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  3rd argument to.
3580: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3590: 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  ) is not NULL, t
35a0: 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  hen it is invoke
35b0: 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 75 6c  d for each resul
35c0: 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20  t row.** coming 
35d0: 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c 75  out of the evalu
35e0: 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
35f0: 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20 61  nts.  ^The 4th a
3600: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
3610: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3620: 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68 20  relayed through 
3630: 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75 6d  to the 1st argum
3640: 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63  ent of each.** c
3650: 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74 69  allback invocati
3660: 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  on.  ^If the cal
3670: 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f  lback pointer to
3680: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3690: 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ** is NULL, then
36a0: 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73 20   no callback is 
36b0: 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64  ever invoked and
36c0: 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72 65   result rows are
36d0: 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  .** ignored..**.
36e0: 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20  ** ^If an error 
36f0: 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76 61  occurs while eva
3700: 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20  luating the SQL 
3710: 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65  statements passe
3720: 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  d into.** sqlite
3730: 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20 65  3_exec(), then e
3740: 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20  xecution of the 
3750: 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65 6e  current statemen
3760: 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73  t stops and.** s
3770: 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65 6d  ubsequent statem
3780: 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65 64  ents are skipped
3790: 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  .  ^If the 5th p
37a0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
37b0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
37c0: 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61   not NULL then a
37d0: 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  ny error message
37e0: 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
37f0: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
3800: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3810: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
3820: 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f  passed back thro
3830: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
3840: 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f  meter..** To avo
3850: 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c  id memory leaks,
3860: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
3870: 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b   should invoke [
3880: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a  sqlite3_free()].
3890: 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73  ** on error mess
38a0: 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  age strings retu
38b0: 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68 65  rned through the
38c0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f   5th parameter o
38d0: 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  f.** of sqlite3_
38e0: 65 78 65 63 28 29 20 61 66 74 65 72 20 74 68 65  exec() after the
38f0: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3900: 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67  tring is no long
3910: 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49  er needed..** ^I
3920: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3930: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3940: 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  xec() is not NUL
3950: 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a  L and no errors.
3960: 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73  ** occur, then s
3970: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 73 65  qlite3_exec() se
3980: 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69  ts the pointer i
3990: 6e 20 69 74 73 20 35 74 68 20 70 61 72 61 6d 65  n its 5th parame
39a0: 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62  ter to.** NULL b
39b0: 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
39c0: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71  .**.** ^If an sq
39d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
39e0: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
39f0: 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69  n-zero, the sqli
3a00: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f  te3_exec().** ro
3a10: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51  utine returns SQ
3a20: 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f  LITE_ABORT witho
3a30: 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  ut invoking the 
3a40: 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61  callback again a
3a50: 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75  nd.** without ru
3a60: 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71  nning any subseq
3a70: 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65  uent SQL stateme
3a80: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
3a90: 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  2nd argument to 
3aa0: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
3ab0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  () callback func
3ac0: 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e  tion is the.** n
3ad0: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
3ae0: 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20   in the result. 
3af0: 20 5e 54 68 65 20 33 72 64 20 61 72 67 75 6d 65   ^The 3rd argume
3b00: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
3b10: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c  3_exec().** call
3b20: 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79  back is an array
3b30: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
3b40: 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64  strings obtained
3b50: 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b   as if from.** [
3b60: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
3b70: 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20  ext()], one for 
3b80: 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49  each column.  ^I
3b90: 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20  f an element of 
3ba0: 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  a.** result row 
3bb0: 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
3bc0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73   corresponding s
3bd0: 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f  tring pointer fo
3be0: 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  r the.** sqlite3
3bf0: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3c00: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
3c10: 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72  er.  ^The 4th ar
3c20: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a  gument to the.**
3c30: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3c40: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61  callback is an a
3c50: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
3c60: 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72   to strings wher
3c70: 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20  e each.** entry 
3c80: 72 65 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e  represents the n
3c90: 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e  ame of correspon
3ca0: 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75  ding result colu
3cb0: 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mn as obtained.*
3cc0: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
3cd0: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a  column_name()]..
3ce0: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e  **.** ^If the 2n
3cf0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
3d00: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3d10: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
3d20: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
3d30: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
3d40: 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74  , or a pointer t
3d50: 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c  hat contains onl
3d60: 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64  y whitespace and
3d70: 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d  /or .** SQL comm
3d80: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51  ents, then no SQ
3d90: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
3da0: 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74   evaluated and t
3db0: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  he database.** i
3dc0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a  s not changed..*
3dd0: 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e  *.** Restriction
3de0: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
3df0: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3e00: 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73 75 72  ation must insur
3e10: 65 20 74 68 61 74 20 74 68 65 20 31 73 74 20 70  e that the 1st p
3e20: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3e30: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20  te3_exec().**   
3e40: 20 20 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e     is a valid an
3e50: 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  d open [database
3e60: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
3e70: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3e80: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63  ation must not c
3e90: 6c 6f 73 65 20 74 68 65 20 5b 64 61 74 61 62 61  lose the [databa
3ea0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
3eb0: 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20  pecified by.**  
3ec0: 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72 61      the 1st para
3ed0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
3ee0: 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71  _exec() while sq
3ef0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3f00: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e  running..** <li>
3f10: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
3f20: 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79   must not modify
3f30: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
3f40: 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20 69  nt text passed i
3f50: 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20  nto.**      the 
3f60: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
3f70: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3f80: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78  while sqlite3_ex
3f90: 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ec() is running.
3fa0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74  .** </ul>.*/.int
3fb0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20   sqlite3_exec(. 
3fc0: 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20   sqlite3*,      
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fe0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
3ff0: 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
4000: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
4010: 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20  *sql,           
4020: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4030: 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
4040: 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20  luated */.  int 
4050: 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  (*callback)(void
4060: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61  *,int,char**,cha
4070: 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61  r**),  /* Callba
4080: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  ck function */. 
4090: 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20   void *,        
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31              /* 1
40c0: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  st argument to c
40d0: 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61  allback */.  cha
40e0: 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20  r **errmsg      
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4100: 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72          /* Error
4110: 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
4120: 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
4130: 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
4140: 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Codes.** KEYWORD
4150: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20  S: {result code 
4160: 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a  definitions}.**.
4170: 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66  ** Many SQLite f
4180: 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
4190: 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c  an integer resul
41a0: 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20  t code from the 
41b0: 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72  set shown.** her
41c0: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  e in order to in
41d0: 64 69 63 61 74 65 20 73 75 63 63 65 73 73 20 6f  dicate success o
41e0: 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  r failure..**.**
41f0: 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73   New error codes
4200: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
4210: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
4220: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
4230: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74  * See also: [ext
4240: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4250: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a  e definitions].*
4260: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4270: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
4280: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
4290: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
42a0: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
42b0: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
42c0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
42d0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
42e0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
42f0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
4300: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
4310: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
4320: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
4330: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
4340: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4350: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
4360: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
4370: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
4380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4390: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
43a0: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
43b0: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
43c0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
43d0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
43e0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
43f0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
4400: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
4410: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4420: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4430: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4440: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4450: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4460: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4470: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
4480: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
4490: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
44a0: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
44b0: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
44c0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
44d0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
44e0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
44f0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
4500: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
4510: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4520: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4530: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4540: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4550: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4560: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4570: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4580: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4590: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
45a0: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
45b0: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
45c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
45d0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
45e0: 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65  * Unknown opcode
45f0: 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65   in sqlite3_file
4600: 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64  _control() */.#d
4610: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c  efine SQLITE_FUL
4620: 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a  L        13   /*
4630: 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65   Insertion faile
4640: 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61  d because databa
4650: 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64  se is full */.#d
4660: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
4670: 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a  TOPEN    14   /*
4680: 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20   Unable to open 
4690: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
46a0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
46b0: 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20  ITE_PROTOCOL    
46c0: 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  15   /* Database
46d0: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65   lock protocol e
46e0: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
46f0: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20  SQLITE_EMPTY    
4700: 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62     16   /* Datab
4710: 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a  ase is empty */.
4720: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
4730: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20  CHEMA      17   
4740: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
4750: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a  schema changed *
4760: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4770: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20  _TOOBIG      18 
4780: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42    /* String or B
4790: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65  LOB exceeds size
47a0: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e   limit */.#defin
47b0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
47c0: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f  INT  19   /* Abo
47d0: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72  rt due to constr
47e0: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a  aint violation *
47f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4800: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20  _MISMATCH    20 
4810: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d    /* Data type m
4820: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69  ismatch */.#defi
4830: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  ne SQLITE_MISUSE
4840: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69        21   /* Li
4850: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72  brary used incor
4860: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  rectly */.#defin
4870: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20  e SQLITE_NOLFS  
4880: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65       22   /* Use
4890: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f  s OS features no
48a0: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68  t supported on h
48b0: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ost */.#define S
48c0: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20  QLITE_AUTH      
48d0: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72    23   /* Author
48e0: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a  ization denied *
48f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4900: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20  _FORMAT      24 
4910: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64    /* Auxiliary d
4920: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65  atabase format e
4930: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4940: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4950: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4960: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4970: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
4980: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
4990: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
49a0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
49b0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
49c0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
49d0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
49e0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20  QLITE_NOTICE    
49f0: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69    27   /* Notifi
4a00: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c  cations from sql
4a10: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
4a30: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a  NING     28   /*
4a40: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73   Warnings from s
4a50: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
4a60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4a70: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
4a80: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4a90: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
4aa0: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
4ab0: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
4ac0: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
4ad0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4ae0: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
4af0: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
4b00: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4b10: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4b20: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
4b30: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
4b40: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4b50: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4b60: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  tions}.**.** In 
4b70: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4b80: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4b90: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4ba0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20  eturn one of 30 
4bb0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75  integer.** [resu
4bc0: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
4bd0: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
4be0: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d  has shown that m
4bf0: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  any of.** these 
4c00: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4c10: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69   too coarse-grai
4c20: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
4c30: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
4c40: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
4c50: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
4c60: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
4c70: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
4c80: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
4c90: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
4ca0: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
4cb0: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
4cc0: 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20  .3.8 and later) 
4cd0: 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f  include.** suppo
4ce0: 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rt for additiona
4cf0: 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74  l result codes t
4d00: 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65  hat provide more
4d10: 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d   detailed inform
4d20: 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65  ation.** about e
4d30: 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b 65 78  rrors. These [ex
4d40: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4d50: 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64  des] are enabled
4d60: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4d70: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4d80: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
4d90: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
4da0: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
4db0: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
4dc0: 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 65 20  ] API.  Or, the 
4dd0: 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20 66 6f  extended code fo
4de0: 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65  r.** the most re
4df0: 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e 20 62  cent error can b
4e00: 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e 67  e obtained using
4e10: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
4e20: 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d  ended_errcode()]
4e30: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
4e40: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
4e50: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4e60: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
4e70: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e80: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
4e90: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
4ea0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
4eb0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4ec0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
4ed0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4ee0: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
4ef0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4f00: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
4f10: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4f20: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
4f30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4f40: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
4f50: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4f60: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
4f70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4f80: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
4f90: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4fa0: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
4fb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4fc0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
4fd0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4fe0: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
4ff0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5000: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5010: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5020: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
5030: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5040: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5050: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5060: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
5070: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5080: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
5090: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
50a0: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
50b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
50c0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
50d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
50e0: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
50f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5100: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5110: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5120: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
5130: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5140: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5150: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5160: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
5170: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5180: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
5190: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
51a0: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
51b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
51c0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
51d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
51e0: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
51f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5200: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5210: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5220: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
5230: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5240: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5250: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5260: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
5270: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5280: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
5290: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52a0: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
52b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52c0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
52d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52e0: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
52f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5300: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5310: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5320: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5330: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5340: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5350: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5360: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5370: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5380: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
5390: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53a0: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
53b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53c0: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
53d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53e0: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
53f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5400: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
5410: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5420: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
5430: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5440: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
5450: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5460: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
5470: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5480: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
5490: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54a0: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
54b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
54c0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
54d0: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
54e0: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
54f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5500: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5510: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5520: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5530: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5540: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
5550: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5560: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
5570: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5580: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5590: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
55a0: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
55b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55c0: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
55d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
55e0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
55f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5600: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
5610: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
5620: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
5630: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5640: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
5650: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
5660: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5670: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5680: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
5690: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
56a0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
56b0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
56c0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
56d0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
56e0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
56f0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5700: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5710: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
5720: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5730: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
5740: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5750: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  NLY_ROLLBACK    
5760: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5770: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  NLY | (3<<8)).#d
5780: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5790: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20  DONLY_DBMOVED   
57a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
57b0: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a  DONLY | (4<<8)).
57c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
57d0: 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20  BORT_ROLLBACK   
57e0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41         (SQLITE_A
57f0: 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23  BORT | (2<<8)).#
5800: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5810: 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20  NSTRAINT_CHECK  
5820: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5830: 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38  NSTRAINT | (1<<8
5840: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5850: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d  E_CONSTRAINT_COM
5860: 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54  MITHOOK   (SQLIT
5870: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5880: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5890: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
58a0: 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53  _FOREIGNKEY   (S
58b0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
58c0: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
58d0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
58e0: 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20  AINT_FUNCTION   
58f0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5900: 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23  AINT | (4<<8)).#
5910: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5920: 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c  NSTRAINT_NOTNULL
5930: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5940: 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38  NSTRAINT | (5<<8
5950: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5960: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49  E_CONSTRAINT_PRI
5970: 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54  MARYKEY   (SQLIT
5980: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5990: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
59a0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
59b0: 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53  _TRIGGER      (S
59c0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
59d0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
59e0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
59f0: 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20  AINT_UNIQUE     
5a00: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5a10: 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23  AINT | (8<<8)).#
5a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5a30: 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20  NSTRAINT_VTAB   
5a40: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5a50: 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38  NSTRAINT | (9<<8
5a60: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5a70: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57  E_CONSTRAINT_ROW
5a80: 49 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  ID        (SQLIT
5a90: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31  E_CONSTRAINT |(1
5aa0: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
5ab0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5ac0: 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53  OVER_WAL      (S
5ad0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5ae0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5af0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5b00: 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53  OVER_ROLLBACK (S
5b10: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5b20: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5b30: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55  QLITE_WARNING_AU
5b40: 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53  TOINDEX       (S
5b50: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20  QLITE_WARNING | 
5b60: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (1<<8))../*.** C
5b70: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
5b80: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
5b90: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
5ba0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
5bb0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
5bc0: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
5bd0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
5be0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
5bf0: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
5c00: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
5c10: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
5c20: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
5c30: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a  .xOpen] method..
5c40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5c50: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
5c60: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5c70: 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  01  /* Ok for sq
5c80: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5c90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ca0: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
5cb0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5cc0: 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  02  /* Ok for sq
5cd0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5ce0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5cf0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20  E_OPEN_CREATE   
5d00: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5d10: 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  04  /* Ok for sq
5d20: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5d30: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5d40: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
5d50: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30  LOSE    0x000000
5d60: 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  08  /* VFS only 
5d70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5d80: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
5d90: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5da0: 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  10  /* VFS only 
5db0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5dc0: 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59  E_OPEN_AUTOPROXY
5dd0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5de0: 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  20  /* VFS only 
5df0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5e00: 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20  E_OPEN_URI      
5e10: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5e20: 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  40  /* Ok for sq
5e30: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5e40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5e50: 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20  E_OPEN_MEMORY   
5e60: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5e70: 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  80  /* Ok for sq
5e80: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5e90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ea0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20  E_OPEN_MAIN_DB  
5eb0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
5ec0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5ed0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ee0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20  E_OPEN_TEMP_DB  
5ef0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
5f00: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5f10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5f20: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
5f30: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34  _DB     0x000004
5f40: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5f50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5f60: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
5f70: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38  NAL     0x000008
5f80: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5f90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5fa0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
5fb0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30  NAL     0x000010
5fc0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5fd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5fe0: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
5ff0: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30  L       0x000020
6000: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6010: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6020: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
6030: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30  URNAL   0x000040
6040: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6050: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6060: 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20  E_OPEN_NOMUTEX  
6070: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30          0x000080
6080: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6090: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
60a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
60b0: 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
60c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30          0x000100
60d0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
60e0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
60f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6100: 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
6110: 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30  HE      0x000200
6120: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6130: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6140: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6150: 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
6160: 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30  CHE     0x000400
6170: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6180: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6190: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
61a0: 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20  E_OPEN_WAL      
61b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30          0x000800
61c0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
61d0: 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a  */../* Reserved:
61e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
61f0: 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30           0x00F00
6200: 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  000 */../*.** CA
6210: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
6220: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a  haracteristics.*
6230: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
6240: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
6250: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73  method of the [s
6260: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
6270: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74  s].** object ret
6280: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20  urns an integer 
6290: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f  which is a vecto
62a0: 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69  r of these.** bi
62b0: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73  t values express
62c0: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65  ing I/O characte
62d0: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d  ristics of the m
62e0: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64  ass storage.** d
62f0: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73  evice that holds
6300: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74   the file that t
6310: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
6320: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72  ethods].** refer
6330: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  s to..**.** The 
6340: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6350: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
6360: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
6370: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
6380: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
6390: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
63a0: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
63b0: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
63c0: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
63d0: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
63e0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
63f0: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
6400: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
6410: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
6420: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
6430: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
6440: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6450: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
6460: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
6470: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
6480: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
6490: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
64a0: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
64b0: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
64c0: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
64d0: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
64e0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
64f0: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
6500: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6510: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
6520: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
6530: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
6540: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
6550: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
6560: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
6570: 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  ).  The SQLITE_I
6580: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6590: 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74  VERWRITE propert
65a0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
65b0: 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c  after reboot fol
65c0: 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f  lowing a crash o
65d0: 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68  r power loss, th
65e0: 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20  e only bytes in 
65f0: 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77  a.** file that w
6600: 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74  ere written at t
6610: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c  he application l
6620: 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20  evel might have 
6630: 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74  changed.** and t
6640: 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74  hat adjacent byt
6650: 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77  es, even bytes w
6660: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73  ithin the same s
6670: 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61  ector are.** gua
6680: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e  ranteed to be un
6690: 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51  changed.  The SQ
66a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c  LITE_IOCAP_UNDEL
66b0: 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e  ETABLE_WHEN_OPEN
66c0: 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74  .** flag indicat
66d0: 65 20 74 68 61 74 20 61 20 66 69 6c 65 20 63 61  e that a file ca
66e0: 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20  nnot be deleted 
66f0: 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a  when open.  The.
6700: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ** SQLITE_IOCAP_
6710: 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69  IMMUTABLE flag i
6720: 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68  ndicates that th
6730: 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20  e file is on.** 
6740: 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20  read-only media 
6750: 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  and cannot be ch
6760: 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70 72  anged even by pr
6770: 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20  ocesses with.** 
6780: 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c 65  elevated privile
6790: 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ges..*/.#define 
67a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
67b0: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20  MIC             
67c0: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23      0x00000001.#
67d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
67e0: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20  CAP_ATOMIC512   
67f0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6800: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
6810: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6820: 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C1K             
6830: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65    0x00000004.#de
6840: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6850: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20  P_ATOMIC2K      
6860: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6870: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  008.#define SQLI
6880: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
6890: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
68a0: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
68b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
68c0: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
68d0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
68e0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
68f0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
6900: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6910: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65  00000040.#define
6920: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6930: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20  OMIC32K         
6940: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a       0x00000080.
6950: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6960: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20  OCAP_ATOMIC64K  
6970: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6980: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
6990: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
69a0: 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20  _APPEND         
69b0: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64     0x00000200.#d
69c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
69d0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20  AP_SEQUENTIAL   
69e0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
69f0: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0400.#define SQL
6a00: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
6a10: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20  TABLE_WHEN_OPEN 
6a20: 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66   0x00000800.#def
6a30: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6a40: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
6a50: 52 49 54 45 20 20 20 20 30 78 30 30 30 30 31 30  RITE    0x000010
6a60: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6a70: 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c  E_IOCAP_IMMUTABL
6a80: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  E              0
6a90: 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a  x00002000../*.**
6aa0: 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20   CAPI3REF: File 
6ab0: 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a  Locking Levels.*
6ac0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
6ad0: 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
6ae0: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
6af0: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72  the second.** ar
6b00: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20  gument to calls 
6b10: 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20  it makes to the 
6b20: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
6b30: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a  ock() methods.**
6b40: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
6b50: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6b60: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ct..*/.#define S
6b70: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20  QLITE_LOCK_NONE 
6b80: 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
6b90: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  ne SQLITE_LOCK_S
6ba0: 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23  HARED        1.#
6bb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6bc0: 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20  CK_RESERVED     
6bd0: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
6be0: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20  E_LOCK_PENDING  
6bf0: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
6c00: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
6c10: 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a  SIVE     4../*.*
6c20: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63  * CAPI3REF: Sync
6c30: 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65  hronization Type
6c40: 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65   Flags.**.** Whe
6c50: 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  n SQLite invokes
6c60: 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74   the xSync() met
6c70: 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71  hod of an.** [sq
6c80: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6c90: 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73  ] object it uses
6ca0: 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f   a combination o
6cb0: 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67  f.** these integ
6cc0: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
6cd0: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
6ce0: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
6cf0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
6d00: 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73  AONLY flag is us
6d10: 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  ed, it means tha
6d20: 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70  t the.** sync op
6d30: 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65  eration only nee
6d40: 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61  ds to flush data
6d50: 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65   to mass storage
6d60: 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f  .  Inode.** info
6d70: 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74  rmation need not
6d80: 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20   be flushed. If 
6d90: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
6da0: 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a  its of the flag.
6db0: 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ** equal SQLITE_
6dc0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61  SYNC_NORMAL, tha
6dd0: 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e  t means to use n
6de0: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65  ormal fsync() se
6df0: 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74  mantics..** If t
6e00: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
6e10: 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ts equal SQLITE_
6e20: 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20  SYNC_FULL, that 
6e30: 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20  means.** to use 
6e40: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
6e50: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20  ullsync instead 
6e60: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a  of fsync()..**.*
6e70: 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65  * Do not confuse
6e80: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
6e90: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
6ea0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
6eb0: 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  gs.** with the [
6ec0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
6ed0: 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b  us]=NORMAL and [
6ee0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
6ef0: 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74  us]=FULL.** sett
6f00: 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63  ings.  The [sync
6f10: 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20  hronous pragma] 
6f20: 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20  determines when 
6f30: 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20  calls to the.** 
6f40: 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64  xSync VFS method
6f50: 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69   occur and appli
6f60: 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72  es uniformly acr
6f70: 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d  oss all platform
6f80: 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  s..** The SQLITE
6f90: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
6fa0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6fb0: 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e  L flags determin
6fc0: 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74  e how.** energet
6fd0: 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f  ic or rigorous o
6fe0: 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73  r forceful the s
6ff0: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ync operations a
7000: 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d  re and.** only m
7010: 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65  ake a difference
7020: 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20   on Mac OSX for 
7030: 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69  the default SQLi
7040: 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69  te code..** (Thi
7050: 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70  rd-party VFS imp
7060: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67  lementations mig
7070: 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65  ht also make the
7080: 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20   distinction.** 
7090: 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53  between SQLITE_S
70a0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
70b0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c  QLITE_SYNC_FULL,
70c0: 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a   but among the.*
70d0: 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  * operating syst
70e0: 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70  ems natively sup
70f0: 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
7100: 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a  , only Mac OSX.*
7110: 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68  * cares about th
7120: 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a  e difference.).*
7130: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
7140: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20  _SYNC_NORMAL    
7150: 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66      0x00002.#def
7160: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
7170: 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78  FULL          0x
7180: 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51  00003.#define SQ
7190: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
71a0: 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a  LY      0x00010.
71b0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
71c0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70   OS Interface Op
71d0: 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a  en File Handle.*
71e0: 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33  *.** An [sqlite3
71f0: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65  _file] object re
7200: 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e  presents an open
7210: 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a   file in the .**
7220: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
7230: 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
7240: 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c  er].  Individual
7250: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a   OS interface.**
7260: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7270: 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f   will.** want to
7280: 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f   subclass this o
7290: 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69  bject by appendi
72a0: 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  ng additional fi
72b0: 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69  elds.** for thei
72c0: 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20  r own use.  The 
72d0: 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69  pMethods entry i
72e0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
72f0: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
7300: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
7310: 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65   that defines me
7320: 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72  thods for perfor
7330: 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72  ming.** I/O oper
7340: 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70  ations on the op
7350: 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65  en file..*/.type
7360: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
7370: 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f  e3_file sqlite3_
7380: 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c  file;.struct sql
7390: 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f  ite3_file {.  co
73a0: 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74  nst struct sqlit
73b0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70  e3_io_methods *p
73c0: 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74  Methods;  /* Met
73d0: 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e  hods for an open
73e0: 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a   file */.};../*.
73f0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
7400: 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56  Interface File V
7410: 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f  irtual Methods O
7420: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72  bject.**.** Ever
7430: 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79  y file opened by
7440: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
7450: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
7460: 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20  populates an.** 
7470: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
7480: 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20  bject (or, more 
7490: 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63  commonly, a subc
74a0: 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  lass of the.** [
74b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
74c0: 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69  ject) with a poi
74d0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
74e0: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
74f0: 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  ct..** This obje
7500: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d  ct defines the m
7510: 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70  ethods used to p
7520: 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f  erform various o
7530: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61  perations.** aga
7540: 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69  inst the open fi
7550: 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  le represented b
7560: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  y the [sqlite3_f
7570: 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  ile] object..**.
7580: 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74  ** If the [sqlit
7590: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
75a0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
75b0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
75c0: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
75d0: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
75e0: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
75f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7600: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
7610: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
7620: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b  ed even if the [
7630: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7640: 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74  n] reported that
7650: 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65   it failed.  The
7660: 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20  .** only way to 
7670: 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74  prevent a call t
7680: 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69  o xClose followi
7690: 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c  ng a failed [sql
76a0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a  ite3_vfs.xOpen].
76b0: 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73  ** is for the [s
76c0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
76d0: 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c  ] to set the sql
76e0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
76f0: 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f  ds element.** to
7700: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
7710: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
7720: 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20  to xSync may be 
7730: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53  one of [SQLITE_S
7740: 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a  YNC_NORMAL] or.*
7750: 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  * [SQLITE_SYNC_F
7760: 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74  ULL].  The first
7770: 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e   choice is the n
7780: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a  ormal fsync()..*
7790: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f  * The second cho
77a0: 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20  ice is a Mac OS 
77b0: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
77c0: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53  .  The [SQLITE_S
77d0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a  YNC_DATAONLY].**
77e0: 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65   flag may be ORe
77f0: 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  d in to indicate
7800: 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64   that only the d
7810: 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a  ata of the file.
7820: 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69  ** and not its i
7830: 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65  node needs to be
7840: 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   synced..**.** T
7850: 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  he integer value
7860: 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64  s to xLock() and
7870: 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f   xUnlock() are o
7880: 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ne of.** <ul>.**
7890: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
78a0: 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69  CK_NONE],.** <li
78b0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  > [SQLITE_LOCK_S
78c0: 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  HARED],.** <li> 
78d0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
78e0: 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  ERVED],.** <li> 
78f0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
7900: 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  DING], or.** <li
7910: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  > [SQLITE_LOCK_E
7920: 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f  XCLUSIVE]..** </
7930: 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69  ul>.** xLock() i
7940: 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ncreases the loc
7950: 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63  k. xUnlock() dec
7960: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
7970: 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65  .** The xCheckRe
7980: 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74  servedLock() met
7990: 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68  hod checks wheth
79a0: 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20  er any database 
79b0: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65  connection,.** e
79c0: 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72  ither in this pr
79d0: 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65  ocess or in some
79e0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20   other process, 
79f0: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53  is holding a RES
7a00: 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e  ERVED,.** PENDIN
7a10: 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  G, or EXCLUSIVE 
7a20: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65  lock on the file
7a30: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72  .  It returns tr
7a40: 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20  ue.** if such a 
7a50: 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20  lock exists and 
7a60: 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e  false otherwise.
7a70: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65  .**.** The xFile
7a80: 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64  Control() method
7a90: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e   is a generic in
7aa0: 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c  terface that all
7ab0: 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46  ows custom.** VF
7ac0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
7ad0: 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f  s to directly co
7ae0: 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69  ntrol an open fi
7af0: 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  le using the.** 
7b00: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
7b10: 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61  ntrol()] interfa
7b20: 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ce.  The second 
7b30: 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73  "op" argument is
7b40: 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f   an.** integer o
7b50: 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72  pcode.  The thir
7b60: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
7b70: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20  generic pointer 
7b80: 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70  intended to.** p
7b90: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74  oint to a struct
7ba0: 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e  ure that may con
7bb0: 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f  tain arguments o
7bc0: 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68  r space in which
7bd0: 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74   to.** write ret
7be0: 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74  urn values.  Pot
7bf0: 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20  ential uses for 
7c00: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
7c10: 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74  ight be.** funct
7c20: 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62  ions to enable b
7c30: 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69  locking locks wi
7c40: 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20  th timeouts, to 
7c50: 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f  change the.** lo
7c60: 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28  cking strategy (
7c70: 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75  for example to u
7c80: 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b  se dot-file lock
7c90: 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a  s), to inquire.*
7ca0: 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74  * about the stat
7cb0: 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72  us of a lock, or
7cc0: 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20   to break stale 
7cd0: 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69  locks.  The SQLi
7ce0: 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72  te.** core reser
7cf0: 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20  ves all opcodes 
7d00: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f  less than 100 fo
7d10: 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a  r its own use..*
7d20: 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f  * A [file contro
7d30: 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74  l opcodes | list
7d40: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73   of opcodes] les
7d50: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76  s than 100 is av
7d60: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c  ailable..** Appl
7d70: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65  ications that de
7d80: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46  fine a custom xF
7d90: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
7da0: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63  d should use opc
7db0: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20  odes.** greater 
7dc0: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69  than 100 to avoi
7dd0: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46  d conflicts.  VF
7de0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
7df0: 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  s should.** retu
7e00: 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  rn [SQLITE_NOTFO
7e10: 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f  UND] for file co
7e20: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68  ntrol opcodes th
7e30: 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
7e40: 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a  * recognize..**.
7e50: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69  ** The xSectorSi
7e60: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  ze() method retu
7e70: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73  rns the sector s
7e80: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65  ize of the.** de
7e90: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c  vice that underl
7ea0: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54  ies the file.  T
7eb0: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69  he sector size i
7ec0: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d  s the.** minimum
7ed0: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20   write that can 
7ee0: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74  be performed wit
7ef0: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a  hout disturbing.
7f00: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69  ** other bytes i
7f10: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  n the file.  The
7f20: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
7f30: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74  ristics().** met
7f40: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69  hod returns a bi
7f50: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62  t vector describ
7f60: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66  ing behaviors of
7f70: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
7f80: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a  ng device:.**.**
7f90: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
7fa0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7fb0: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  IC].** <li> [SQL
7fc0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7fd0: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  512].** <li> [SQ
7fe0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7ff0: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C1K].** <li> [SQ
8000: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8010: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C2K].** <li> [SQ
8020: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8030: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C4K].** <li> [SQ
8040: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8050: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C8K].** <li> [SQ
8060: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8070: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C16K].** <li> [S
8080: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8090: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC32K].** <li> [
80a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
80b0: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC64K].** <li> 
80c0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41  [SQLITE_IOCAP_SA
80d0: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c  FE_APPEND].** <l
80e0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
80f0: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20  _SEQUENTIAL].** 
8100: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
8110: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8120: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
8130: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
8140: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
8150: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
8160: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
8170: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
8180: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
8190: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
81a0: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
81b0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
81c0: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
81d0: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
81e0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
81f0: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
8200: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
8210: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
8220: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
8230: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
8240: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
8250: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
8260: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
8270: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
8280: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
8290: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
82a0: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
82b0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
82c0: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
82d0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
82e0: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
82f0: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
8300: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
8310: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
8320: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
8330: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
8340: 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61  )..**.** If xRea
8350: 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49  d() returns SQLI
8360: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
8370: 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f  EAD it must also
8380: 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20   fill.** in the 
8390: 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20  unread portions 
83a0: 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69  of the buffer wi
83b0: 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53  th zeros.  A VFS
83c0: 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74   that.** fails t
83d0: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
83e0: 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65  t reads might se
83f0: 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77  em to work.  How
8400: 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65  ever,.** failure
8410: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68   to zero-fill sh
8420: 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65  ort reads will e
8430: 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74  ventually lead t
8440: 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  o.** database co
8450: 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  rruption..*/.typ
8460: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
8470: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73  te3_io_methods s
8480: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
8490: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
84a0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  3_io_methods {. 
84b0: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20   int iVersion;. 
84c0: 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73   int (*xClose)(s
84d0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
84e0: 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71   int (*xRead)(sq
84f0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69  lite3_file*, voi
8500: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
8510: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8520: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69  t);.  int (*xWri
8530: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
8540: 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
8550: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
8560: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
8570: 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74    int (*xTruncat
8580: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8590: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
85a0: 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  size);.  int (*x
85b0: 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69  Sync)(sqlite3_fi
85c0: 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  le*, int flags);
85d0: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69  .  int (*xFileSi
85e0: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
85f0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
8600: 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20   *pSize);.  int 
8610: 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  (*xLock)(sqlite3
8620: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
8630: 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73  int (*xUnlock)(s
8640: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8650: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65  t);.  int (*xChe
8660: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28  ckReservedLock)(
8670: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8680: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
8690: 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72  int (*xFileContr
86a0: 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ol)(sqlite3_file
86b0: 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20  *, int op, void 
86c0: 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a  *pArg);.  int (*
86d0: 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c  xSectorSize)(sql
86e0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
86f0: 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72  nt (*xDeviceChar
8700: 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c  acteristics)(sql
8710: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f  ite3_file*);.  /
8720: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
8730: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
8740: 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74  rsion 1 */.  int
8750: 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69   (*xShmMap)(sqli
8760: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69  te3_file*, int i
8770: 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e  Pg, int pgsz, in
8780: 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65  t, void volatile
8790: 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  **);.  int (*xSh
87a0: 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  mLock)(sqlite3_f
87b0: 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74  ile*, int offset
87c0: 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61  , int n, int fla
87d0: 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53  gs);.  void (*xS
87e0: 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74  hmBarrier)(sqlit
87f0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
8800: 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71   (*xShmUnmap)(sq
8810: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8820: 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20   deleteFlag);.  
8830: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
8840: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
8850: 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e  ersion 2 */.  in
8860: 74 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69  t (*xFetch)(sqli
8870: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8880: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
8890: 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a  int iAmt, void *
88a0: 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  *pp);.  int (*xU
88b0: 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f  nfetch)(sqlite3_
88c0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
88d0: 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 64  nt64 iOfst, void
88e0: 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f   *p);.  /* Metho
88f0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
8900: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33  id for version 3
8910: 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f   */.  /* Additio
8920: 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20  nal methods may 
8930: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
8940: 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d  re releases */.}
8950: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
8960: 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65  F: Standard File
8970: 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73   Control Opcodes
8980: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66  .** KEYWORDS: {f
8990: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
89a0: 64 65 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72  des} {file contr
89b0: 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a  ol opcode}.**.**
89c0: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
89d0: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63  onstants are opc
89e0: 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69  odes for the xFi
89f0: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
8a00: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
8a10: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
8a20: 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74  object and for t
8a30: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
8a40: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69  _control()].** i
8a50: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
8a60: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
8a70: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63  L_LOCKSTATE] opc
8a80: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ode is used for 
8a90: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73  debugging.  This
8aa0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65  .** opcode cause
8ab0: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  s the xFileContr
8ac0: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69  ol method to wri
8ad0: 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  te the current s
8ae0: 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c  tate of.** the l
8af0: 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c  ock (one of [SQL
8b00: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20  ITE_LOCK_NONE], 
8b10: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
8b20: 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  RED],.** [SQLITE
8b30: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
8b40: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
8b50: 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49  NDING], or [SQLI
8b60: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
8b70: 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69  E]).** into an i
8b80: 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20  nteger that the 
8b90: 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f  pArg argument po
8ba0: 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61  ints to. This ca
8bb0: 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75  pability.** is u
8bc0: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
8bd0: 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64  ng and only need
8be0: 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  s to be supporte
8bf0: 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45  d when SQLITE_TE
8c00: 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64  ST.** is defined
8c10: 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  ..** <ul>.** <li
8c20: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
8c30: 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54  SIZE_HINT]].** T
8c40: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
8c50: 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f  _SIZE_HINT] opco
8c60: 64 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51  de is used by SQ
8c70: 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65  Lite to give the
8c80: 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20   VFS.** layer a 
8c90: 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67  hint of how larg
8ca0: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
8cb0: 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f  ile will grow to
8cc0: 20 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a   be during the.*
8cd0: 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61  * current transa
8ce0: 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e  ction.  This hin
8cf0: 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  t is not guarant
8d00: 65 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61  eed to be accura
8d10: 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20  te but it.** is 
8d20: 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68  often close.  Th
8d30: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53  e underlying VFS
8d40: 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f   might choose to
8d50: 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74   preallocate dat
8d60: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70  abase.** file sp
8d70: 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69  ace based on thi
8d80: 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20  s hint in order 
8d90: 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74  to help writes t
8da0: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
8db0: 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65  * file run faste
8dc0: 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  r..**.** <li>[[S
8dd0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
8de0: 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20  K_SIZE]].** The 
8df0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48  [SQLITE_FCNTL_CH
8e00: 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65  UNK_SIZE] opcode
8e10: 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75   is used to requ
8e20: 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53  est that the VFS
8e30: 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20  .** extends and 
8e40: 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61  truncates the da
8e50: 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63  tabase file in c
8e60: 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20  hunks of a size 
8e70: 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
8e80: 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f  the user. The fo
8e90: 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
8ea0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
8eb0: 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64  ontrol()] should
8ec0: 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e   .** point to an
8ed0: 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69   integer (type i
8ee0: 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  nt) containing t
8ef0: 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a  he new chunk-siz
8f00: 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20  e to use.** for 
8f10: 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61  the nominated da
8f20: 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69  tabase. Allocati
8f30: 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ng database file
8f40: 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a   space in large.
8f50: 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31  ** chunks (say 1
8f60: 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d  MB at a time), m
8f70: 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73  ay reduce file-s
8f80: 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74  ystem fragmentat
8f90: 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f  ion and.** impro
8fa0: 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f  ve performance o
8fb0: 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a  n some systems..
8fc0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
8fd0: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
8fe0: 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b  INTER]].** The [
8ff0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
9000: 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  E_POINTER] opcod
9010: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74  e is used to obt
9020: 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  ain a pointer.**
9030: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
9040: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73  _file] object as
9050: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
9060: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
9070: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
9080: 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c  n.  See the [sql
9090: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
90a0: 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  l()] documentati
90b0: 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  on for.** additi
90c0: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
90d0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
90e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
90f0: 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20  OMITTED]].** No 
9100: 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a  longer in use..*
9110: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9120: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a  E_FCNTL_SYNC]].*
9130: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
9140: 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65  NTL_SYNC] opcode
9150: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
9160: 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69  ternally by SQLi
9170: 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74  te and.** sent t
9180: 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69  o the VFS immedi
9190: 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65  ately before the
91a0: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73   xSync method is
91b0: 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a   invoked on a.**
91c0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 64   database file d
91d0: 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69  escriptor. Or, i
91e0: 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  f the xSync meth
91f0: 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  od is not invoke
9200: 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68  d .** because th
9210: 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69  e user has confi
9220: 67 75 72 65 64 20 53 51 4c 69 74 65 20 77 69 74  gured SQLite wit
9230: 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79  h .** [PRAGMA sy
9240: 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47  nchronous | PRAG
9250: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f  MA synchronous=O
9260: 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  FF] it is invoke
9270: 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f  d in place .** o
9280: 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  f the xSync meth
9290: 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65  od. In most case
92a0: 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61  s, the pointer a
92b0: 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77  rgument passed w
92c0: 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65  ith.** this file
92d0: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c  -control is NULL
92e0: 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68  . However, if th
92f0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
9300: 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a  is being synced.
9310: 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61 20  ** as part of a 
9320: 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63  multi-database c
9330: 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d  ommit, the argum
9340: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20  ent points to a 
9350: 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  nul-terminated.*
9360: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
9370: 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63 74  ing the transact
9380: 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72  ions master-jour
9390: 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56  nal file name. V
93a0: 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f  FSes that .** do
93b0: 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73   not need this s
93c0: 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c  ignal should sil
93d0: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
93e0: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63  s opcode. Applic
93f0: 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c  ations .** shoul
9400: 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69  d not call [sqli
9410: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
9420: 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70  ()] with this op
9430: 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f  code as doing so
9440: 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74   may .** disrupt
9450: 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f   the operation o
9460: 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65  f the specialize
9470: 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20  d VFSes that do 
9480: 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a  require it.  .**
9490: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
94a0: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
94b0: 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20  ASETWO]].** The 
94c0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
94d0: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f  MMIT_PHASETWO] o
94e0: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
94f0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
9500: 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73   SQLite.** and s
9510: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 61  ent to the VFS a
9520: 66 74 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  fter a transacti
9530: 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d  on has been comm
9540: 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  itted immediatel
9550: 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20  y.** but before 
9560: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
9570: 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20  unlocked. VFSes 
9580: 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64  that do not need
9590: 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20   this signal.** 
95a0: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
95b0: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
95c0: 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  de. Applications
95d0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
95e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
95f0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
9600: 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73  h this opcode as
9610: 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69   doing so may di
9620: 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70  srupt the .** op
9630: 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  eration of the s
9640: 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73  pecialized VFSes
9650: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65   that do require
9660: 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69   it.  .**.** <li
9670: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9680: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d  WIN32_AV_RETRY]]
9690: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
96a0: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
96b0: 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73  RETRY] opcode is
96c0: 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75   used to configu
96d0: 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20  re automatic.** 
96e0: 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64  retry counts and
96f0: 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63   intervals for c
9700: 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20  ertain disk I/O 
9710: 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74  operations for t
9720: 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56  he.** windows [V
9730: 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  FS] in order to 
9740: 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65  provide robustne
9750: 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e  ss in the presen
9760: 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69  ce of.** anti-vi
9770: 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42  rus programs.  B
9780: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77  y default, the w
9790: 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20  indows VFS will 
97a0: 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c  retry file read,
97b0: 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20  .** file write, 
97c0: 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20  and file delete 
97d0: 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f  operations up to
97e0: 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20   10 times, with 
97f0: 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35  a delay.** of 25
9800: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65   milliseconds be
9810: 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72  fore the first r
9820: 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68  etry and with th
9830: 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69  e delay increasi
9840: 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69  ng.** by an addi
9850: 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73  tional 25 millis
9860: 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68  econds with each
9870: 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72   subsequent retr
9880: 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  y.  This.** opco
9890: 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20  de allows these 
98a0: 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72  two values (10 r
98b0: 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69  etries and 25 mi
98c0: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65  lliseconds of de
98d0: 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64  lay).** to be ad
98e0: 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c  justed.  The val
98f0: 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20  ues are changed 
9900: 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65  for all database
9910: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
9920: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
9930: 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72  process.  The ar
9940: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
9950: 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20  ter to an array 
9960: 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65  of two.** intege
9970: 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72  rs where the fir
9980: 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 65  st integer i the
9990: 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74   new retry count
99a0: 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a   and the second.
99b0: 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68  ** integer is th
99c0: 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74  e delay.  If eit
99d0: 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e  her integer is n
99e0: 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
99f0: 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20  e setting.** is 
9a00: 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20  not changed but 
9a10: 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f  instead the prio
9a20: 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  r value of that 
9a30: 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74  setting is writt
9a40: 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61  en.** into the a
9a50: 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f  rray entry, allo
9a60: 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74  wing the current
9a70: 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20   retry settings 
9a80: 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f  to be.** interro
9a90: 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e  gated.  The zDbN
9aa0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
9ab0: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
9ac0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9ad0: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d  TL_PERSIST_WAL]]
9ae0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
9af0: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
9b00: 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  AL] opcode is us
9b10: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65  ed to set or que
9b20: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73  ry the.** persis
9b30: 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74  tent [WAL | Writ
9b40: 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74  e Ahead Log] set
9b50: 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c  ting.  By defaul
9b60: 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79  t, the auxiliary
9b70: 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20  .** write ahead 
9b80: 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d  log and shared m
9b90: 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64  emory files used
9ba0: 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e   for transaction
9bb0: 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20   control.** are 
9bc0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
9bd0: 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c  leted when the l
9be0: 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e  atest connection
9bf0: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
9c00: 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74  .** closes.  Set
9c10: 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20  ting persistent 
9c20: 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20  WAL mode causes 
9c30: 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70  those files to p
9c40: 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20  ersist after.** 
9c50: 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69  close.  Persisti
9c60: 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20  ng the files is 
9c70: 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65  useful when othe
9c80: 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74  r processes that
9c90: 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20   do not.** have 
9ca0: 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e  write permission
9cb0: 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72   on the director
9cc0: 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  y containing the
9cd0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
9ce0: 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74  ant.** to read t
9cf0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9d00: 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64  , as the WAL and
9d10: 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66   shared memory f
9d20: 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a  iles must exist.
9d30: 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20  ** in order for 
9d40: 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20  the database to 
9d50: 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  be readable.  Th
9d60: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
9d70: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
9d80: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9d90: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  ] for this opcod
9da0: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f  e should be a po
9db0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
9dc0: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74  ger..** That int
9dd0: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73  eger is 0 to dis
9de0: 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20  able persistent 
9df0: 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f  WAL mode or 1 to
9e00: 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65   enable persiste
9e10: 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20  nt.** WAL mode. 
9e20: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20   If the integer 
9e30: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69  is -1, then it i
9e40: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
9e50: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  th the current.*
9e60: 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63  * WAL persistenc
9e70: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  e setting..**.**
9e80: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9e90: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
9ea0: 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68  ERWRITE]].** ^Th
9eb0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9ec0: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
9ed0: 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  ITE] opcode is u
9ee0: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
9ef0: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
9f00: 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65  stent "powersafe
9f10: 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22  -overwrite" or "
9f20: 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20  PSOW" setting.  
9f30: 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67  The PSOW setting
9f40: 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74  .** determines t
9f50: 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  he [SQLITE_IOCAP
9f60: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
9f70: 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65  RITE] bit of the
9f80: 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61  .** xDeviceChara
9f90: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f  cteristics metho
9fa0: 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70  ds. The fourth p
9fb0: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
9fc0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9fd0: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
9fe0: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
9ff0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
a000: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
a010: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
a020: 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d  to disable zero-
a030: 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31  damage mode or 1
a040: 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d   to enable zero-
a050: 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20  damage.** mode. 
a060: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20   If the integer 
a070: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69  is -1, then it i
a080: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
a090: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  th the current.*
a0a0: 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f  * zero-damage mo
a0b0: 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a  de setting..**.*
a0c0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a0d0: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d  CNTL_OVERWRITE]]
a0e0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
a0f0: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
a100: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f  ] opcode is invo
a110: 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66  ked by SQLite af
a120: 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61  ter opening.** a
a130: 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69   write transacti
a140: 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  on to indicate t
a150: 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69  hat, unless it i
a160: 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f  s rolled back fo
a170: 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e  r some.** reason
a180: 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74  , the entire dat
a190: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20  abase file will 
a1a0: 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62  be overwritten b
a1b0: 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a  y the current .*
a1c0: 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54  * transaction. T
a1d0: 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56  his is used by V
a1e0: 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73  ACUUM operations
a1f0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a200: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
a210: 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ME]].** ^The [SQ
a220: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
a230: 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62  ME] opcode can b
a240: 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
a250: 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a   the names of.**
a260: 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20   all [VFSes] in 
a270: 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20  the VFS stack.  
a280: 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66  The names are of
a290: 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61   all VFS shims a
a2a0: 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  nd the.** final 
a2b0: 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53  bottom-level VFS
a2c0: 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74   are written int
a2d0: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
a2e0: 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69  d from .** [sqli
a2f0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
a300: 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  d the result is 
a310: 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68  stored in the ch
a320: 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  ar* variable.** 
a330: 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20  that the fourth 
a340: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71  parameter of [sq
a350: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
a360: 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e  ol()] points to.
a370: 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69  .** The caller i
a380: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
a390: 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65  r freeing the me
a3a0: 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20  mory when done. 
a3b0: 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20   As with.** all 
a3c0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74  file-control act
a3d0: 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e  ions, there is n
a3e0: 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  o guarantee that
a3f0: 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61   this will actua
a400: 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69  lly.** do anythi
a410: 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f  ng.  Callers sho
a420: 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74  uld initialize t
a430: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
a440: 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  e to a NULL.** p
a450: 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74  ointer in case t
a460: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
a470: 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e   is not implemen
a480: 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d  ted.  This file-
a490: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e  control.** is in
a4a0: 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e  tended for diagn
a4b0: 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a  ostic use only..
a4c0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a4d0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a4e0: 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61  ].** ^Whenever a
a4f0: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d   [PRAGMA] statem
a500: 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61  ent is parsed, a
a510: 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  n [SQLITE_FCNTL_
a520: 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65  PRAGMA] .** file
a530: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74   control is sent
a540: 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71   to the open [sq
a550: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
a560: 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  ct corresponding
a570: 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62  .** to the datab
a580: 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63  ase file to whic
a590: 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61  h the pragma sta
a5a0: 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e  tement refers. ^
a5b0: 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  The argument.** 
a5c0: 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  to the [SQLITE_F
a5d0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
a5e0: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20  e control is an 
a5f0: 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e  array of.** poin
a600: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
a610: 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63  (char**) in whic
a620: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65  h the second ele
a630: 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61  ment of the arra
a640: 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  y.** is the name
a650: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61   of the pragma a
a660: 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65  nd the third ele
a670: 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75  ment is the argu
a680: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70  ment to the.** p
a690: 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66  ragma or NULL if
a6a0: 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20   the pragma has 
a6b0: 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54  no argument.  ^T
a6c0: 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  he handler for a
a6d0: 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  n.** [SQLITE_FCN
a6e0: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
a6f0: 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69  control can opti
a700: 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20  onally make the 
a710: 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a  first element.**
a720: 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61   of the char** a
a730: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f  rgument point to
a740: 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e   a string obtain
a750: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
a760: 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f  _mprintf()].** o
a770: 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74  r the equivalent
a780: 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67   and that string
a790: 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65   will become the
a7a0: 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70   result of the p
a7b0: 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20  ragma or.** the 
a7c0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66  error message if
a7d0: 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c   the pragma fail
a7e0: 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  s. ^If the.** [S
a7f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
a800: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
a810: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
a820: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e  _NOTFOUND], then
a830: 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41   normal .** [PRA
a840: 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20  GMA] processing 
a850: 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20  continues.  ^If 
a860: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
a870: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c  L_PRAGMA].** fil
a880: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
a890: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
a8a0: 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61  hen the parser a
a8b0: 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
a8c0: 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c  ** VFS has handl
a8d0: 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74  ed the PRAGMA it
a8e0: 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72  self and the par
a8f0: 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20  ser generates a 
a900: 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65  no-op.** prepare
a910: 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49  d statement.  ^I
a920: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  f the [SQLITE_FC
a930: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
a940: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
a950: 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63  .** any result c
a960: 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ode other than [
a970: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53  SQLITE_OK] or [S
a980: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
a990: 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74   that means.** t
a9a0: 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f  hat the VFS enco
a9b0: 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72  untered an error
a9c0: 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20   while handling 
a9d0: 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64  the [PRAGMA] and
a9e0: 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74   the.** compilat
a9f0: 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d  ion of the PRAGM
aa00: 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20  A fails with an 
aa10: 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51  error.  ^The [SQ
aa20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
aa30: 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72  A].** file contr
aa40: 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 65  ol occurs at the
aa50: 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72   beginning of pr
aa60: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61  agma statement a
aa70: 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a  nalysis and so.*
aa80: 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20  * it is able to 
aa90: 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69  override built-i
aaa0: 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65  n [PRAGMA] state
aab0: 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ments..**.** <li
aac0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
aad0: 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a  BUSYHANDLER]].**
aae0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
aaf0: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d  NTL_BUSYHANDLER]
ab00: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  .** file-control
ab10: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
ab20: 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65  by SQLite on the
ab30: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 68   database file h
ab40: 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79  andle.** shortly
ab50: 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70 65   after it is ope
ab60: 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ned in order to 
ab70: 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d  provide a custom
ab80: 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73 73   VFS with access
ab90: 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65  .** to the conne
aba0: 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64  ctions busy-hand
abb0: 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68  ler callback. Th
abc0: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66  e argument is of
abd0: 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a   type (void **).
abe0: 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66  ** - an array of
abf0: 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61   two (void *) va
ac00: 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74 20  lues. The first 
ac10: 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c  (void *) actuall
ac20: 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61  y points.** to a
ac30: 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70   function of typ
ac40: 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20  e (int (*)(void 
ac50: 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f  *)). In order to
ac60: 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e   invoke the conn
ac70: 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d  ections.** busy-
ac80: 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75  handler, this fu
ac90: 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65  nction should be
aca0: 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68   invoked with th
acb0: 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a  e second (void *
acc0: 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61  ) in.** the arra
acd0: 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72  y as the only ar
ace0: 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65  gument. If it re
acf0: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
ad00: 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69  then the operati
ad10: 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
ad20: 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20 72  retried. If it r
ad30: 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65  eturns zero, the
ad40: 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75   custom VFS shou
ad50: 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a  ld abandon the.*
ad60: 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74  * current operat
ad70: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ion..**.** <li>[
ad80: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45  [SQLITE_FCNTL_TE
ad90: 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20  MPFILENAME]].** 
ada0: 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e  ^Application can
adb0: 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c   invoke the [SQL
adc0: 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49  ITE_FCNTL_TEMPFI
add0: 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e  LENAME] file-con
ade0: 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20  trol.** to have 
adf0: 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20  SQLite generate 
ae00: 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  a.** temporary f
ae10: 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68  ilename using th
ae20: 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d  e same algorithm
ae30: 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65   that is followe
ae40: 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a  d to generate.**
ae50: 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e   temporary filen
ae60: 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61  ames for TEMP ta
ae70: 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69  bles and other i
ae80: 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54  nternal uses.  T
ae90: 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73  he.** argument s
aea0: 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a  hould be a char*
aeb0: 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20  * which will be 
aec0: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
aed0: 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74  filename.** writ
aee0: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  ten into memory 
aef0: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
af00: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
af10: 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68  .  The caller sh
af20: 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b  ould.** invoke [
af30: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
af40: 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f  on the result to
af50: 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20   avoid a memory 
af60: 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  leak..**.** <li>
af70: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d  [[SQLITE_FCNTL_M
af80: 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68  MAP_SIZE]].** Th
af90: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
afa0: 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20  MMAP_SIZE] file 
afb0: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
afc0: 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74 20  to query or set 
afd0: 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e  the.** maximum n
afe0: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 74  umber of bytes t
aff0: 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64  hat will be used
b000: 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70   for memory-mapp
b010: 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61  ed I/O..** The a
b020: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
b030: 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20  nter to a value 
b040: 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f  of type sqlite3_
b050: 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73  int64 that.** is
b060: 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78   an advisory max
b070: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62  imum number of b
b080: 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65  ytes in the file
b090: 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20   to memory map. 
b0a0: 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   The.** pointer 
b0b0: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
b0c0: 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75  ith the old valu
b0d0: 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73  e.  The limit is
b0e0: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a   not changed if.
b0f0: 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69  ** the value ori
b100: 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20  ginally pointed 
b110: 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  to is negative, 
b120: 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72 65  and so the curre
b130: 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e  nt limit .** can
b140: 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20 70   be queried by p
b150: 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e  assing in a poin
b160: 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76  ter to a negativ
b170: 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a  e number.  This.
b180: 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  ** file-control 
b190: 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
b1a0: 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ly to implement 
b1b0: 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  [PRAGMA mmap_siz
b1c0: 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  e]..**.** <li>[[
b1d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
b1e0: 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  CE]].** The [SQL
b1f0: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  ITE_FCNTL_TRACE]
b200: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72   file control pr
b210: 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 79 20  ovides advisory 
b220: 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74  information.** t
b230: 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 74 20  o the VFS about 
b240: 77 68 61 74 20 74 68 65 20 68 69 67 68 65 72 20  what the higher 
b250: 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 53 51  layers of the SQ
b260: 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 20 64  Lite stack are d
b270: 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69  oing..** This fi
b280: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73  le control is us
b290: 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20 61  ed by some VFS a
b2a0: 63 74 69 76 69 74 79 20 74 72 61 63 69 6e 67 20  ctivity tracing 
b2b0: 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20  [shims]..** The 
b2c0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a 65  argument is a ze
b2d0: 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
b2e0: 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c 61  ring.  Higher la
b2f0: 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53  yers in the.** S
b300: 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79 20  QLite stack may 
b310: 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e 63  generate instanc
b320: 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20  es of this file 
b330: 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68  control if.** th
b340: 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46 43  e [SQLITE_USE_FC
b350: 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69  NTL_TRACE] compi
b360: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
b370: 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a  s enabled..**.**
b380: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
b390: 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a  NTL_HAS_MOVED]].
b3a0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
b3b0: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20  CNTL_HAS_MOVED] 
b3c0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74  file control int
b3d0: 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67 75  erprets its argu
b3e0: 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69  ment as a.** poi
b3f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
b400: 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 65 73  er and it writes
b410: 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20   a boolean into 
b420: 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 65 70  that integer dep
b430: 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65  ending.** on whe
b440: 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
b450: 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72 65  file has been re
b460: 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72  named, moved, or
b470: 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20 69   deleted since i
b480: 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20 6f  t.** was first o
b490: 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  pened..**.** <li
b4a0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b4b0: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45  WIN32_SET_HANDLE
b4c0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
b4d0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45  E_FCNTL_WIN32_SE
b4e0: 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65  T_HANDLE] opcode
b4f0: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
b500: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
b510: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
b520: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
b530: 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20 74  method to swap t
b540: 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 77  he file handle w
b550: 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70  ith the one.** p
b560: 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
b570: 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e 20   pArg argument. 
b580: 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79   This capability
b590: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
b5a0: 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f  testing.** and o
b5b0: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20  nly needs to be 
b5c0: 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53  supported when S
b5d0: 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64 65  QLITE_TEST is de
b5e0: 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75  fined..**.** </u
b5f0: 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
b600: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
b610: 54 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  TATE            
b620: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
b630: 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_GET_LOCKPROX
b640: 59 46 49 4c 45 20 20 20 20 20 20 20 20 20 20 20  YFILE           
b650: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
b660: 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_SET_LOCKPROXY
b670: 46 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20  FILE            
b680: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
b690: 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  E_LAST_ERRNO    
b6a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
b6b0: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
b6c0: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
b6d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35                 5
b6e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b6f0: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
b700: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
b710: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b720: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
b730: 52 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23  R            7.#
b740: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b750: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
b760: 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64              8.#d
b770: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b780: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52  TL_WIN32_AV_RETR
b790: 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65  Y          9.#de
b7a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b7b0: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20  L_PERSIST_WAL   
b7c0: 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66           10.#def
b7d0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b7e0: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20  _OVERWRITE      
b7f0: 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69          11.#defi
b800: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b810: 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20  VFSNAME         
b820: 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e         12.#defin
b830: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
b840: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
b850: 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65  TE    13.#define
b860: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52   SQLITE_FCNTL_PR
b870: 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
b880: 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20       14.#define 
b890: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
b8a0: 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20  YHANDLER        
b8b0: 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53      15.#define S
b8c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
b8d0: 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20  FILENAME        
b8e0: 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51     16.#define SQ
b8f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
b900: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  SIZE            
b910: 20 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c    18.#define SQL
b920: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20  ITE_FCNTL_TRACE 
b930: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
b940: 20 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   19.#define SQLI
b950: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
b960: 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ED              
b970: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  20.#define SQLIT
b980: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20  E_FCNTL_SYNC    
b990: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
b9a0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
b9b0: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
b9c0: 41 53 45 54 57 4f 20 20 20 20 20 20 20 20 32 32  ASETWO        22
b9d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b9e0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f  FCNTL_WIN32_SET_
b9f0: 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a  HANDLE       23.
ba00: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
ba10: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a   Mutex Handle.**
ba20: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f  .** The mutex mo
ba30: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69  dule within SQLi
ba40: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69  te defines [sqli
ba50: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65  te3_mutex] to be
ba60: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20   an.** abstract 
ba70: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78  type for a mutex
ba80: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51   object.  The SQ
ba90: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20  Lite core never 
baa0: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20  looks.** at the 
bab0: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
bac0: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73  ntation of an [s
bad0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20  qlite3_mutex].  
bae0: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73  It only.** deals
baf0: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74   with pointers t
bb00: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  o the [sqlite3_m
bb10: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  utex] object..**
bb20: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20  .** Mutexes are 
bb30: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73  created using [s
bb40: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
bb50: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  oc()]..*/.typede
bb60: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
bb70: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d  _mutex sqlite3_m
bb80: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  utex;../*.** CAP
bb90: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
bba0: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ace Object.**.**
bbb0: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
bbc0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
bbd0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
bbe0: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
bbf0: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69  ween.** the SQLi
bc00: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
bc10: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
bc20: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
bc30: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
bc40: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
bc50: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
bc60: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
bc70: 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74  stem".  See.** t
bc80: 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f  he [VFS | VFS do
bc90: 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
bca0: 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61   further informa
bcb0: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
bcc0: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65  value of the iVe
bcd0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69  rsion field is i
bce0: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d  nitially 1 but m
bcf0: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a  ay be larger in.
bd00: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  ** future versio
bd10: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  ns of SQLite.  A
bd20: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
bd30: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
bd40: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65   to this.** obje
bd50: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72  ct when the iVer
bd60: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e  sion value is in
bd70: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74  creased.  Note t
bd80: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72  hat the structur
bd90: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  e.** of the sqli
bda0: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63  te3_vfs object c
bdb0: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72  hanges in the tr
bdc0: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65  ansaction betwee
bdd0: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  n.** SQLite vers
bde0: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e  ion 3.5.9 and 3.
bdf0: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20  6.0 and yet the 
be00: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77  iVersion field w
be10: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69  as not.** modifi
be20: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a  ed..**.** The sz
be30: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20  OsFile field is 
be40: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
be50: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69  subclassed [sqli
be60: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72  te3_file].** str
be70: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74  ucture used by t
be80: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68  his VFS.  mxPath
be90: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69  name is the maxi
bea0: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a  mum length of.**
beb0: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74   a pathname in t
bec0: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52  his VFS..**.** R
bed0: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65  egistered sqlite
bee0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72  3_vfs objects ar
bef0: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b  e kept on a link
bf00: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62  ed list formed b
bf10: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70  y.** the pNext p
bf20: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71  ointer.  The [sq
bf30: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
bf40: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  er()].** and [sq
bf50: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
bf60: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  ster()] interfac
bf70: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c  es manage this l
bf80: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65  ist.** in a thre
bf90: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68  ad-safe way.  Th
bfa0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  e [sqlite3_vfs_f
bfb0: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ind()] interface
bfc0: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65  .** searches the
bfd0: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20   list.  Neither 
bfe0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
bff0: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53  code nor the VFS
c000: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
c010: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68  on should use th
c020: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
c030: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74  .**.** The pNext
c040: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e   field is the on
c050: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20  ly field in the 
c060: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73  sqlite3_vfs.** s
c070: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51  tructure that SQ
c080: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d  Lite will ever m
c090: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77  odify.  SQLite w
c0a0: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a  ill only access.
c0b0: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ** or modify thi
c0c0: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f  s field while ho
c0d0: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c  lding a particul
c0e0: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e  ar static mutex.
c0f0: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
c100: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
c110: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67   modify anything
c120: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69   within the sqli
c130: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63  te3_vfs.** objec
c140: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63  t once the objec
c150: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73  t has been regis
c160: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tered..**.** The
c170: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c   zName field hol
c180: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ds the name of t
c190: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20  he VFS module.  
c1a0: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a  The name must.**
c1b0: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73   be unique acros
c1c0: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65  s all VFS module
c1d0: 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  s..**.** [[sqlit
c1e0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a  e3_vfs.xOpen]].*
c1f0: 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
c200: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46  tees that the zF
c210: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
c220: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73  r to xOpen.** is
c230: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
c240: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67  ointer or string
c250: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
c260: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28  m xFullPathname(
c270: 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e  ) with an option
c280: 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e  al suffix added.
c290: 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78  .** ^If a suffix
c2a0: 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65   is added to the
c2b0: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
c2c0: 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a  eter, it will.**
c2d0: 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69   consist of a si
c2e0: 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74  ngle "-" charact
c2f0: 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e  er followed by n
c300: 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31  o more than.** 1
c310: 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61  1 alphanumeric a
c320: 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63  nd/or "-" charac
c330: 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  ters..** ^SQLite
c340: 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74   further guarant
c350: 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ees that.** the 
c360: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76  string will be v
c370: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67  alid and unchang
c380: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28  ed until xClose(
c390: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20  ) is.** called. 
c3a0: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  Because of the p
c3b0: 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
c3c0: 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  ,.** the [sqlite
c3d0: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65  3_file] can safe
c3e0: 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74  ly store a point
c3f0: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c  er to the.** fil
c400: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64  ename if it need
c410: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68  s to remember th
c420: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73  e filename for s
c430: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49  ome reason..** I
c440: 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  f the zFilename 
c450: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
c460: 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  en is a NULL poi
c470: 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a  nter then xOpen.
c480: 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69  ** must invent i
c490: 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79  ts own temporary
c4a0: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69   name for the fi
c4b0: 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74  le.  ^Whenever t
c4c0: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65  he .** xFilename
c4d0: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55   parameter is NU
c4e0: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20  LL it will also 
c4f0: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
c500: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61   the.** flags pa
c510: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63  rameter will inc
c520: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
c530: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
c540: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
c550: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  s argument to xO
c560: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61  pen() includes a
c570: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a  ll bits set in.*
c580: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  * the flags argu
c590: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
c5a0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72  _open_v2()].  Or
c5b0: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   if [sqlite3_ope
c5c0: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  n()].** or [sqli
c5d0: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73  te3_open16()] is
c5e0: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67   used, then flag
c5f0: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65  s includes at le
c600: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ast.** [SQLITE_O
c610: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
c620: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
c630: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f  EATE]. .** If xO
c640: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69  pen() opens a fi
c650: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65  le read-only the
c660: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46  n it sets *pOutF
c670: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75  lags to.** inclu
c680: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
c690: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65  READONLY].  Othe
c6a0: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46  r bits in *pOutF
c6b0: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e  lags may be set.
c6c0: 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20  .**.** ^(SQLite 
c6d0: 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e  will also add on
c6e0: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
c6f0: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
c700: 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c  xOpen().** call,
c710: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
c720: 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f  e object being o
c730: 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  pened:.**.** <ul
c740: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  >.** <li>  [SQLI
c750: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
c760: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
c770: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
c780: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
c790: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
c7a0: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
c7b0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
c7c0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
c7d0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52   [SQLITE_OPEN_TR
c7e0: 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c  ANSIENT_DB].** <
c7f0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
c800: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  N_SUBJOURNAL].**
c810: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
c820: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
c830: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
c840: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a  LITE_OPEN_WAL].*
c850: 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
c860: 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70  The file I/O imp
c870: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20  lementation can 
c880: 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74  use the object t
c890: 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20  ype flags to.** 
c8a0: 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69  change the way i
c8b0: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c  t deals with fil
c8c0: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  es.  For example
c8d0: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
c8e0: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  .** that does no
c8f0: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61  t care about cra
c900: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72  sh recovery or r
c910: 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61  ollback might ma
c920: 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f  ke.** the open o
c930: 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  f a journal file
c940: 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65   a no-op.  Write
c950: 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61  s to this journa
c960: 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20  l would.** also 
c970: 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61  be no-ops, and a
c980: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  ny attempt to re
c990: 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77  ad the journal w
c9a0: 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53  ould return.** S
c9b0: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72  QLITE_IOERR.  Or
c9c0: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
c9d0: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e  ion might recogn
c9e0: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62  ize that a datab
c9f0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c  ase.** file will
ca00: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61   be doing page-a
ca10: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65  ligned sector re
ca20: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69  ads and writes i
ca30: 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72  n a random.** or
ca40: 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69  der and set up i
ca50: 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d  ts I/O subsystem
ca60: 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a   accordingly..**
ca70: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74  .** SQLite might
ca80: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
ca90: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
caa0: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
cab0: 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  n method:.**.** 
cac0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
cad0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
cae0: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e  ONCLOSE].** <li>
caf0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
cb00: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c  CLUSIVE].** </ul
cb10: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  >.**.** The [SQL
cb20: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
cb30: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61  NCLOSE] flag mea
cb40: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  ns the file shou
cb50: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64  ld be.** deleted
cb60: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73   when it is clos
cb70: 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  ed.  ^The [SQLIT
cb80: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
cb90: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65  LOSE].** will be
cba0: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61   set for TEMP da
cbb0: 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69  tabases and thei
cbc0: 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e  r journals, tran
cbd0: 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73  sient.** databas
cbe0: 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e  es, and subjourn
cbf0: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  als..**.** ^The 
cc00: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
cc10: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20  LUSIVE] flag is 
cc20: 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63  always used in c
cc30: 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69  onjunction.** wi
cc40: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
cc50: 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67  PEN_CREATE] flag
cc60: 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68  , which are both
cc70: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61   directly.** ana
cc80: 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f  logous to the O_
cc90: 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54  EXCL and O_CREAT
cca0: 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f   flags of the PO
ccb0: 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50  SIX open().** AP
ccc0: 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  I.  The SQLITE_O
ccd0: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c  PEN_EXCLUSIVE fl
cce0: 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20  ag, when paired 
ccf0: 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c  with the .** SQL
cd00: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c  ITE_OPEN_CREATE,
cd10: 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69   is used to indi
cd20: 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73  cate that file s
cd30: 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20  hould always.** 
cd40: 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20  be created, and 
cd50: 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72  that it is an er
cd60: 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64  ror if it alread
cd70: 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20  y exists..** It 
cd80: 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73  is <i>not</i> us
cd90: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
cda0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
cdb0: 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72  e opened .** for
cdc0: 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73   exclusive acces
cdd0: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61  s..**.** ^At lea
cde0: 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65  st szOsFile byte
cdf0: 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20  s of memory are 
ce00: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c  allocated by SQL
ce10: 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74  ite.** to hold t
ce20: 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  he  [sqlite3_fil
ce30: 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73  e] structure pas
ce40: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
ce50: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
ce60: 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65  xOpen.  The xOpe
ce70: 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f  n method does no
ce80: 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c  t have to.** all
ce90: 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74  ocate the struct
cea0: 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a  ure; it should j
ceb0: 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20  ust fill it in. 
cec0: 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68   Note that.** th
ced0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d  e xOpen method m
cee0: 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69  ust set the sqli
cef0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
cf00: 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61  s to either.** a
cf10: 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f   valid [sqlite3_
cf20: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
cf30: 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20  ct or to NULL.  
cf40: 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a  xOpen must do.**
cf50: 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68   this even if th
cf60: 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53  e open fails.  S
cf70: 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68  QLite expects th
cf80: 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  at the sqlite3_f
cf90: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20  ile.pMethods.** 
cfa0: 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  element will be 
cfb0: 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65  valid after xOpe
cfc0: 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64  n returns regard
cfd0: 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63  less of the succ
cfe0: 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72  ess.** or failur
cff0: 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63  e of the xOpen c
d000: 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  all..**.** [[sql
d010: 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73  ite3_vfs.xAccess
d020: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73  ]].** ^The flags
d030: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63   argument to xAc
d040: 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53  cess() may be [S
d050: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
d060: 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  STS].** to test 
d070: 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63  for the existenc
d080: 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20  e of a file, or 
d090: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
d0a0: 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20  EADWRITE] to.** 
d0b0: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
d0c0: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20  ile is readable 
d0d0: 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72  and writable, or
d0e0: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
d0f0: 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  READ].** to test
d100: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
d110: 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64  is at least read
d120: 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65  able.   The file
d130: 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72   can be a.** dir
d140: 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53  ectory..**.** ^S
d150: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79  QLite will alway
d160: 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65  s allocate at le
d170: 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31  ast mxPathname+1
d180: 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a   bytes for the.*
d190: 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  * output buffer 
d1a0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20  xFullPathname.  
d1b0: 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f  The exact size o
d1c0: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
d1d0: 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70  fer.** is also p
d1e0: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d  assed as a param
d1f0: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65  eter to both  me
d200: 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75  thods. If the ou
d210: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
d220: 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75  s not large enou
d230: 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54  gh, [SQLITE_CANT
d240: 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20  OPEN] should be 
d250: 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20  returned. Since 
d260: 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c  this is.** handl
d270: 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72  ed as a fatal er
d280: 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76  ror by SQLite, v
d290: 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  fs implementatio
d2a0: 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76  ns should endeav
d2b0: 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74  or.** to prevent
d2c0: 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67   this by setting
d2d0: 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61   mxPathname to a
d2e0: 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61   sufficiently la
d2f0: 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  rge value..**.**
d300: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
d310: 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43  (), xSleep(), xC
d320: 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e  urrentTime(), an
d330: 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  d xCurrentTimeIn
d340: 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  t64().** interfa
d350: 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69  ces are not stri
d360: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74  ctly a part of t
d370: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62  he filesystem, b
d380: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69  ut they are.** i
d390: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56  ncluded in the V
d3a0: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72  FS structure for
d3b0: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a   completeness..*
d3c0: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
d3d0: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74  s() function att
d3e0: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20  empts to return 
d3f0: 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20  nBytes bytes.** 
d400: 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20  of good-quality 
d410: 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
d420: 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72  zOut.  The retur
d430: 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68  n value is.** th
d440: 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20  e actual number 
d450: 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64  of bytes of rand
d460: 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e  omness obtained.
d470: 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29  .** The xSleep()
d480: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74   method causes t
d490: 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61  he calling threa
d4a0: 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61  d to sleep for a
d4b0: 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e  t.** least the n
d4c0: 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65  umber of microse
d4d0: 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54  conds given.  ^T
d4e0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  he xCurrentTime(
d4f0: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
d500: 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79  rns a Julian Day
d510: 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20   Number for the 
d520: 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64  current date and
d530: 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c   time as.** a fl
d540: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
d550: 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72  ue..** ^The xCur
d560: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
d570: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20  method returns, 
d580: 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  as an integer, t
d590: 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79  he Julian.** Day
d5a0: 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69   Number multipli
d5b0: 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28  ed by 86400000 (
d5c0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  the number of mi
d5d0: 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a  lliseconds in .*
d5e0: 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29  * a 24-hour day)
d5f0: 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .  .** ^SQLite w
d600: 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72  ill use the xCur
d610: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
d620: 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68  method to get th
d630: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74  e current.** dat
d640: 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68  e and time if th
d650: 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61  at method is ava
d660: 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73  ilable (if iVers
d670: 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20  ion is 2 or .** 
d680: 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20  greater and the 
d690: 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
d6a0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e   is not NULL) an
d6b0: 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b  d will fall back
d6c0: 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54  .** to xCurrentT
d6d0: 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e  ime() if xCurren
d6e0: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20  tTimeInt64() is 
d6f0: 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a  unavailable..**.
d700: 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74  ** ^The xSetSyst
d710: 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79  emCall(), xGetSy
d720: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20  stemCall(), and 
d730: 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28  xNestSystemCall(
d740: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
d750: 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20  are not used by 
d760: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e  the SQLite core.
d770: 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c    These optional
d780: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
d790: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73  provided.** by s
d7a0: 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63  ome VFSes to fac
d7b0: 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20  ilitate testing 
d7c0: 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e  of the VFS code.
d7d0: 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a   By overriding .
d7e0: 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  ** system calls 
d7f0: 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75  with functions u
d800: 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c  nder its control
d810: 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d  , a test program
d820: 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65   can.** simulate
d830: 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f   faults and erro
d840: 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61  r conditions tha
d850: 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73  t would otherwis
d860: 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a  e be difficult.*
d870: 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20  * or impossible 
d880: 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20  to induce.  The 
d890: 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61  set of system ca
d8a0: 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  lls that can be 
d8b0: 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61  overridden.** va
d8c0: 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46  ries from one VF
d8d0: 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e  S to another, an
d8e0: 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69  d from one versi
d8f0: 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56  on of the same V
d900: 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78  FS to the.** nex
d910: 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  t.  Applications
d920: 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20   that use these 
d930: 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20  interfaces must 
d940: 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20  be prepared for 
d950: 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66  any.** or all of
d960: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
d970: 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20  s to be NULL or 
d980: 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69  for their behavi
d990: 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  or to change.** 
d9a0: 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65  from one release
d9b0: 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41   to the next.  A
d9c0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74  pplications must
d9d0: 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20   not attempt to 
d9e0: 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66  access.** any of
d9f0: 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69   these methods i
da00: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f  f the iVersion o
da10: 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73  f the VFS is les
da20: 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70  s than 3..*/.typ
da30: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
da40: 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f  te3_vfs sqlite3_
da50: 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69  vfs;.typedef voi
da60: 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63  d (*sqlite3_sysc
da70: 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a  all_ptr)(void);.
da80: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
da90: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
daa0: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
dab0: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
dac0: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72  sion number (cur
dad0: 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69  rently 3) */.  i
dae0: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20  nt szOsFile;    
daf0: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20          /* Size 
db00: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71  of subclassed sq
db10: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20  lite3_file */.  
db20: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20  int mxPathname; 
db30: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
db40: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  mum file pathnam
db50: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71  e length */.  sq
db60: 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74  lite3_vfs *pNext
db70: 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72  ;      /* Next r
db80: 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f  egistered VFS */
db90: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
dba0: 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e  Name;       /* N
dbb0: 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74  ame of this virt
dbc0: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20  ual file system 
dbd0: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
dbe0: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ata;          /*
dbf0: 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c   Pointer to appl
dc00: 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63  ication-specific
dc10: 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28   data */.  int (
dc20: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
dc30: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
dc40: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
dc50: 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20  _file*,.        
dc60: 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73         int flags
dc70: 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73  , int *pOutFlags
dc80: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65  );.  int (*xDele
dc90: 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  te)(sqlite3_vfs*
dca0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
dcb0: 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72  ame, int syncDir
dcc0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65  );.  int (*xAcce
dcd0: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
dce0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
dcf0: 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20  ame, int flags, 
dd00: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
dd10: 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68   int (*xFullPath
dd20: 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  name)(sqlite3_vf
dd30: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
dd40: 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c  zName, int nOut,
dd50: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
dd60: 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29  void *(*xDlOpen)
dd70: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
dd80: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
dd90: 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a  name);.  void (*
dda0: 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65  xDlError)(sqlite
ddb0: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
ddc0: 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  e, char *zErrMsg
ddd0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44  );.  void (*(*xD
dde0: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66  lSym)(sqlite3_vf
ddf0: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  s*,void*, const 
de00: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28  char *zSymbol))(
de10: 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a  void);.  void (*
de20: 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  xDlClose)(sqlite
de30: 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a  3_vfs*, void*);.
de40: 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e    int (*xRandomn
de50: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
de60: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
de70: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74  ar *zOut);.  int
de80: 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74   (*xSleep)(sqlit
de90: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63  e3_vfs*, int mic
dea0: 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e  roseconds);.  in
deb0: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
dec0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ded0: 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  double*);.  int 
dee0: 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29  (*xGetLastError)
def0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
df00: 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f  nt, char *);.  /
df10: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
df20: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
df30: 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65  version 1 of the
df40: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
df50: 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69  ct.  ** definiti
df60: 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20  on.  Those that 
df70: 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64  follow are added
df80: 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72   in version 2 or
df90: 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e   later.  */.  in
dfa0: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
dfb0: 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76  Int64)(sqlite3_v
dfc0: 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  fs*, sqlite3_int
dfd0: 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  64*);.  /*.  ** 
dfe0: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
dff0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
e000: 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65  s 1 and 2 of the
e010: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
e020: 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62  ct..  ** Those b
e030: 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72  elow are for ver
e040: 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74  sion 3 and great
e050: 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28  er..  */.  int (
e060: 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xSetSystemCall)
e070: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
e080: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
e090: 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  , sqlite3_syscal
e0a0: 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65  l_ptr);.  sqlite
e0b0: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a  3_syscall_ptr (*
e0c0: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xGetSystemCall)(
e0d0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
e0e0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
e0f0: 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ;.  const char *
e100: 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c  (*xNextSystemCal
e110: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
e120: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
e130: 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  me);.  /*.  ** T
e140: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
e150: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
e160: 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20   1 through 3 of 
e170: 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
e180: 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20  bject..  ** New 
e190: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
e1a0: 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65  pended in figure
e1b0: 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20   versions.  The 
e1c0: 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61  iVersion.  ** va
e1d0: 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65  lue will increme
e1e0: 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73  nt whenever this
e1f0: 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a   happens. .  */.
e200: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
e210: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
e220: 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65  e xAccess VFS me
e230: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
e240: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
e250: 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61  ts can be used a
e260: 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  s the third para
e270: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
e280: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f  xAccess method o
e290: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  f an [sqlite3_vf
e2a0: 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79  s] object.  They
e2b0: 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68   determine.** wh
e2c0: 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69  at kind of permi
e2d0: 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65  ssions the xAcce
e2e0: 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f  ss method is loo
e2f0: 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74  king for..** Wit
e300: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
e310: 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63  EXISTS, the xAcc
e320: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69  ess method.** si
e330: 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74  mply checks whet
e340: 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69  her the file exi
e350: 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  sts..** With SQL
e360: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
e370: 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73  RITE, the xAcces
e380: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
e390: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e  ks whether the n
e3a0: 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69  amed directory i
e3b0: 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20  s both readable 
e3c0: 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20  and writable.** 
e3d0: 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c  (in other words,
e3e0: 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65   if files can be
e3f0: 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c   added, removed,
e400: 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74   and renamed wit
e410: 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63  hin.** the direc
e420: 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51  tory)..** The SQ
e430: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
e440: 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69  WRITE constant i
e450: 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64  s currently used
e460: 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20   only by the.** 
e470: 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
e480: 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74  ctory pragma], t
e490: 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64  hough this could
e4a0: 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74   change in a fut
e4b0: 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f  ure.** release o
e4c0: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74  f SQLite..** Wit
e4d0: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
e4e0: 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73  READ, the xAcces
e4f0: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
e500: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
e510: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e  ile is readable.
e520: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43    The SQLITE_ACC
e530: 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e  ESS_READ constan
e540: 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c  t is.** currentl
e550: 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68  y unused, though
e560: 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65   it might be use
e570: 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65  d in a future re
e580: 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
e590: 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
e5a0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
e5b0: 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65  STS    0.#define
e5c0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
e5d0: 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20  EADWRITE 1   /* 
e5e0: 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74  Used by PRAGMA t
e5f0: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
e600: 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ory */.#define S
e610: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
e620: 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e  D      2   /* Un
e630: 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
e640: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
e650: 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  or the xShmLock 
e660: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
e670: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
e680: 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
e690: 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b  the various lock
e6a0: 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ing operations.*
e6b0: 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65  * allowed by the
e6c0: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
e6d0: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   of [sqlite3_io_
e6e0: 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a  methods].  The.*
e6f0: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20  * following are 
e700: 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63  the only legal c
e710: 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66  ombinations of f
e720: 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  lags to the.** x
e730: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a  ShmLock method:.
e740: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
e750: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  i>  SQLITE_SHM_L
e760: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
e770: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
e780: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
e790: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
e7a0: 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20  CLUSIVE.** <li> 
e7b0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
e7c0: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
e7d0: 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
e7e0: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
e7f0: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
e800: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c  XCLUSIVE.** </ul
e810: 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c  >.**.** When unl
e820: 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65  ocking, the same
e830: 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55   SHARED or EXCLU
e840: 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62  SIVE flag must b
e850: 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a  e supplied as.**
e860: 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68   was given no th
e870: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
e880: 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  lock.  .**.** Th
e890: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
e8a0: 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e  d can transition
e8b0: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
e8c0: 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a  d and SHARED or.
e8d0: 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  ** between unloc
e8e0: 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56  ked and EXCLUSIV
e8f0: 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72  E.  It cannot tr
e900: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
e910: 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45   SHARED.** and E
e920: 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65  XCLUSIVE..*/.#de
e930: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
e940: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23  UNLOCK       1.#
e950: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
e960: 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32  M_LOCK         2
e970: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e980: 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20  SHM_SHARED      
e990: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
e9a0: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20  E_SHM_EXCLUSIVE 
e9b0: 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     8../*.** CAPI
e9c0: 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53  3REF: Maximum xS
e9d0: 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a  hmLock index.**.
e9e0: 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20  ** The xShmLock 
e9f0: 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74  method on [sqlit
ea00: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d  e3_io_methods] m
ea10: 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a  ay use values.**
ea20: 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74   between 0 and t
ea30: 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20  his upper bound 
ea40: 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20  as its "offset" 
ea50: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
ea60: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c   SQLite core wil
ea70: 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20  l never attempt 
ea80: 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65  to acquire or re
ea90: 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20  lease a.** lock 
eaa0: 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20  outside of this 
eab0: 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65  range.*/.#define
eac0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43   SQLITE_SHM_NLOC
ead0: 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a  K        8.../*.
eae0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69  ** CAPI3REF: Ini
eaf0: 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69  tialize The SQLi
eb00: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
eb10: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
eb20: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
eb30: 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  ne initializes t
eb40: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62  he.** SQLite lib
eb50: 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69  rary.  ^The sqli
eb60: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72  te3_shutdown() r
eb70: 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f  outine.** deallo
eb80: 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72  cates any resour
eb90: 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c  ces that were al
eba0: 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
ebb0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
ebc0: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
ebd0: 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20  es are designed 
ebe0: 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73  to aid in proces
ebf0: 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  s initialization
ec00: 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e   and.** shutdown
ec10: 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73   on embedded sys
ec20: 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69  tems.  Workstati
ec30: 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  on applications 
ec40: 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20  using.** SQLite 
ec50: 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20  normally do not 
ec60: 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65  need to invoke e
ec70: 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72  ither of these r
ec80: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41  outines..**.** A
ec90: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
eca0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
ecb0: 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20   an "effective" 
ecc0: 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a  call if it is.**
ecd0: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
ece0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ecf0: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ze() is invoked 
ed00: 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74  during the lifet
ed10: 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72  ime of.** the pr
ed20: 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20  ocess, or if it 
ed30: 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  is the first tim
ed40: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
ed50: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
ed60: 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  d.** following a
ed70: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
ed80: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28  _shutdown().  ^(
ed90: 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76  Only an effectiv
eda0: 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c  e call.** of sql
edb0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
edc0: 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69  ) does any initi
edd0: 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20  alization.  All 
ede0: 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61  other calls.** a
edf0: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
ee00: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ps.)^.**.** A ca
ee10: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
ee20: 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22  utdown() is an "
ee30: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
ee40: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
ee50: 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71  st.** call to sq
ee60: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
ee70: 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20   since the last 
ee80: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ee90: 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a  ze().  ^(Only.**
eea0: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
eeb0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
eec0: 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e  utdown() does an
eed0: 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69  y deinitializati
eee0: 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72  on..** All other
eef0: 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20   valid calls to 
ef00: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
ef10: 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  () are harmless 
ef20: 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
ef30: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
ef40: 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61  ialize() interfa
ef50: 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  ce is threadsafe
ef60: 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68  , but sqlite3_sh
ef70: 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e  utdown().** is n
ef80: 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ot.  The sqlite3
ef90: 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65  _shutdown() inte
efa0: 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20  rface must only 
efb0: 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  be called from a
efc0: 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61  .** single threa
efd0: 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61  d.  All open [da
efe0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
eff0: 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73  ns] must be clos
f000: 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74  ed and all.** ot
f010: 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75  her SQLite resou
f020: 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61  rces must be dea
f030: 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74  llocated prior t
f040: 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71  o invoking.** sq
f050: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f060: 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74  ..**.** Among ot
f070: 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c  her things, ^sql
f080: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f090: 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a  ) will invoke.**
f0a0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
f0b0: 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20  ().  Similarly, 
f0c0: 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  ^sqlite3_shutdow
f0d0: 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f  n().** will invo
f0e0: 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  ke sqlite3_os_en
f0f0: 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  d()..**.** ^The 
f100: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f110: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  ze() routine ret
f120: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
f130: 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20   on success..** 
f140: 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ^If for some rea
f150: 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69  son, sqlite3_ini
f160: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61  tialize() is una
f170: 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a  ble to initializ
f180: 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79  e.** the library
f190: 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20   (perhaps it is 
f1a0: 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
f1b0: 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f  te a needed reso
f1c0: 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20  urce such.** as 
f1d0: 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75  a mutex) it retu
f1e0: 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  rns an [error co
f1f0: 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  de] other than [
f200: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
f210: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
f220: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
f230: 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e  ine is called in
f240: 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79  ternally by many
f250: 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
f260: 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74   interfaces so t
f270: 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69  hat an applicati
f280: 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20  on usually does 
f290: 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69  not need to.** i
f2a0: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
f2b0: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
f2c0: 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  tly.  For exampl
f2d0: 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  e, [sqlite3_open
f2e0: 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c  ()].** calls sql
f2f0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f300: 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20  ) so the SQLite 
f310: 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20  library will be 
f320: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
f330: 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65   initialized whe
f340: 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  n [sqlite3_open(
f350: 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20  )] is called if 
f360: 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e  it has not be in
f370: 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72  itialized.** alr
f380: 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c  eady.  ^However,
f390: 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
f3a0: 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20  mpiled with the 
f3b0: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
f3c0: 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c  OINIT].** compil
f3d0: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74  e-time option, t
f3e0: 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69  hen the automati
f3f0: 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  c calls to sqlit
f400: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
f410: 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61  ** are omitted a
f420: 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
f430: 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c  on must call sql
f440: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f450: 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72  ) directly.** pr
f460: 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
f470: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
f480: 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61  terface.  For ma
f490: 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74  ximum portabilit
f4a0: 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f  y,.** it is reco
f4b0: 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
f4c0: 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73  lications always
f4d0: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
f4e0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
f4f0: 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74  directly prior t
f500: 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
f510: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
f520: 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65  ce.  Future rele
f530: 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ases.** of SQLit
f540: 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68  e may require th
f550: 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  is.  In other wo
f560: 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f  rds, the behavio
f570: 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77  r exhibited.** w
f580: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
f590: 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
f5a0: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
f5b0: 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20  T] might become 
f5c0: 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62  the.** default b
f5d0: 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20  ehavior in some 
f5e0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
f5f0: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
f600: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
f610: 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  nit() routine do
f620: 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  es operating-sys
f630: 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  tem specific.** 
f640: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
f650: 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  f the SQLite lib
f660: 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74  rary.  The sqlit
f670: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72  e3_os_end().** r
f680: 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68  outine undoes th
f690: 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69  e effect of sqli
f6a0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
f6b0: 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a  Typical tasks.**
f6c0: 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68   performed by th
f6d0: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63  ese routines inc
f6e0: 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  lude allocation 
f6f0: 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a  or deallocation.
f700: 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73  ** of static res
f710: 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69  ources, initiali
f720: 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c  zation of global
f730: 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73   variables,.** s
f740: 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61  etting up a defa
f750: 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
f760: 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74  ] module, or set
f770: 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66  ting up.** a def
f780: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
f790: 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  on using [sqlite
f7a0: 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a  3_config()]..**.
f7b0: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
f7c0: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
f7d0: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71  invoke either sq
f7e0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
f7f0: 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  ** or sqlite3_os
f800: 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e  _end() directly.
f810: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
f820: 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e  n should only in
f830: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
f840: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
f850: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
f860: 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65  n().  The sqlite
f870: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69  3_os_init().** i
f880: 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c  nterface is call
f890: 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
f8a0: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
f8b0: 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20  ialize() and.** 
f8c0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
f8d0: 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71   is called by sq
f8e0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f8f0: 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a  .  Appropriate.*
f900: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
f910: 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  s for sqlite3_os
f920: 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69  _init() and sqli
f930: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
f940: 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  are built into S
f950: 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73  QLite when it is
f960: 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e   compiled for Un
f970: 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20  ix, Windows, or 
f980: 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63  OS/2..** When [c
f990: 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62  ustom builds | b
f9a0: 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70  uilt for other p
f9b0: 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73  latforms].** (us
f9c0: 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
f9d0: 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70  OS_OTHER=1] comp
f9e0: 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
f9f0: 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74  on) the applicat
fa00: 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20  ion must supply 
fa10: 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65  a suitable imple
fa20: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
fa30: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
fa40: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
fa50: 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70  s_end().  An app
fa60: 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
fa70: 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  d.** implementat
fa80: 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ion of sqlite3_o
fa90: 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69  s_init() or sqli
faa0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
fab0: 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c  must return [SQL
fac0: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
fad0: 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65  ss and some othe
fae0: 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75  r [error code] u
faf0: 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a  pon.** failure..
fb00: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69  */.int sqlite3_i
fb10: 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b  nitialize(void);
fb20: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75  .int sqlite3_shu
fb30: 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74  tdown(void);.int
fb40: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
fb50: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
fb60: 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29  te3_os_end(void)
fb70: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
fb80: 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54  F: Configuring T
fb90: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
fba0: 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  y.**.** The sqli
fbb0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
fbc0: 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
fbd0: 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f  o make global co
fbe0: 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63  nfiguration.** c
fbf0: 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65  hanges to SQLite
fc00: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e   in order to tun
fc10: 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  e SQLite to the 
fc20: 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f  specific needs o
fc30: 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
fc40: 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75  tion.  The defau
fc50: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
fc60: 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
fc70: 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c  for most.** appl
fc80: 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20  ications and so 
fc90: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
fca0: 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65  usually not nece
fcb0: 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a  ssary.  It is.**
fcc0: 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70   provided to sup
fcd0: 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63  port rare applic
fce0: 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73  ations with unus
fcf0: 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ual needs..**.**
fd00: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
fd10: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
fd20: 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66  is not threadsaf
fd30: 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  e.  The applicat
fd40: 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75  ion.** must insu
fd50: 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72  re that no other
fd60: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
fd70: 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62  es are invoked b
fd80: 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61  y other.** threa
fd90: 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  ds while sqlite3
fda0: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e  _config() is run
fdb0: 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f  ning.  Furthermo
fdc0: 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  re, sqlite3_conf
fdd0: 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  ig().** may only
fde0: 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f   be invoked prio
fdf0: 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69  r to library ini
fe00: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e  tialization usin
fe10: 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e  g.** [sqlite3_in
fe20: 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  itialize()] or a
fe30: 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79  fter shutdown by
fe40: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
fe50: 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  wn()]..** ^If sq
fe60: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
fe70: 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  s called after [
fe80: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
fe90: 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65  ze()] and before
fea0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
feb0: 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74  tdown()] then it
fec0: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c   will return SQL
fed0: 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e  ITE_MISUSE..** N
fee0: 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68  ote, however, th
fef0: 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66  at ^sqlite3_conf
ff00: 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c  ig() can be call
ff10: 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
ff20: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
ff30: 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63  ion of an applic
ff40: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73  ation-defined [s
ff50: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
ff60: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  ]..**.** The fir
ff70: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
ff80: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
ff90: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  is an integer.**
ffa0: 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
ffb0: 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74  option] that det
ffc0: 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20  ermines.** what 
ffd0: 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69  property of SQLi
ffe0: 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66  te is to be conf
fff0: 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75  igured.  Subsequ
10000 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a  ent arguments.**
10010 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
10020 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72  on the [configur
10030 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a  ation option].**
10040 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
10050 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57  gument..**.** ^W
10060 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74  hen a configurat
10070 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ion option is se
10080 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t, sqlite3_confi
10090 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  g() returns [SQL
100a0 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20  ITE_OK]..** ^If 
100b0 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  the option is un
100c0 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20  known or SQLite 
100d0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74  is unable to set
100e0 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74   the option.** t
100f0 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
10100 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
10110 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
10120 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
10130 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e  _config(int, ...
10140 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
10150 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61  EF: Configure da
10160 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10170 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ns.**.** The sql
10180 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
10190 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
101a0 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
101b0 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
101c0 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
101d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
101e0 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
101f0 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
10200 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
10210 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
10220 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
10230 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
10240 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10250 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
10260 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
10270 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54  gument)..**.** T
10280 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
10290 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  nt to sqlite3_db
102a0 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29  _config(D,V,...)
102b0 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c    is the.** [SQL
102c0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
102d0 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75  KASIDE | configu
102e0 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61  ration verb] - a
102f0 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a  n integer code .
10300 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  ** that indicate
10310 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66  s what aspect of
10320 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
10330 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
10340 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a  ing configured..
10350 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  ** Subsequent ar
10360 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70  guments vary dep
10370 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f  ending on the co
10380 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
10390 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ..**.** ^Calls t
103a0 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
103b0 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c  fig() return SQL
103c0 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e  ITE_OK if and on
103d0 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c  ly if.** the cal
103e0 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  l is considered 
103f0 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69  successful..*/.i
10400 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  nt sqlite3_db_co
10410 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69  nfig(sqlite3*, i
10420 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  nt op, ...);../*
10430 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
10440 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
10450 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41  Routines.**.** A
10460 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
10470 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
10480 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
10490 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a  between SQLite.*
104a0 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20  * and low-level 
104b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
104c0 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  n routines..**.*
104d0 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
104e0 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e   used in only on
104f0 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53  e place in the S
10500 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
10510 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
10520 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
10530 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74  this object is t
10540 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
10550 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
10560 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f  g()] when the co
10570 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10580 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  on is.** [SQLITE
10590 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20  _CONFIG_MALLOC] 
105a0 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
105b0 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a  G_GETMALLOC].  .
105c0 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61  ** By creating a
105d0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
105e0 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  is object.** and
105f0 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
10600 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
10610 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
10620 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e  ALLOC]).** durin
10630 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  g configuration,
10640 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
10650 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61  can specify an a
10660 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
10670 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10680 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51  subsystem for SQ
10690 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20  Lite to use for 
106a0 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79  all of its.** dy
106b0 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65  namic memory nee
106c0 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  ds..**.** Note t
106d0 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73  hat SQLite comes
106e0 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62   with several [b
106f0 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
10700 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68  llocators].** th
10710 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79  at are perfectly
10720 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68   adequate for th
10730 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d  e overwhelming m
10740 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  ajority of appli
10750 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74  cations.** and t
10760 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20  hat this object 
10770 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74  is only useful t
10780 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74  o a tiny minorit
10790 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
107a0 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61  s.** with specia
107b0 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  lized memory all
107c0 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d  ocation requirem
107d0 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65  ents.  This obje
107e0 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73  ct is.** also us
107f0 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
10800 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f  g of SQLite in o
10810 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  rder to specify 
10820 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
10830 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
10840 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65  or that simulate
10850 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d  s memory out-of-
10860 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e  memory condition
10870 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f  s in.** order to
10880 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c   verify that SQL
10890 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61  ite recovers gra
108a0 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63  cefully from suc
108b0 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e  h.** conditions.
108c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c  .**.** The xMall
108d0 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e  oc, xRealloc, an
108e0 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20  d xFree methods 
108f0 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74  must work like t
10900 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20  he.** malloc(), 
10910 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72  realloc() and fr
10920 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66  ee() functions f
10930 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
10940 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e   C library..** ^
10950 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
10960 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
10970 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
10980 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77   xRealloc is alw
10990 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75  ays a value retu
109a0 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20  rned by a prior 
109b0 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70  call to xRoundup
109c0 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68  ..**.** xSize sh
109d0 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
109e0 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
109f0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
10a00 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75  ation.** previou
10a10 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
10a20 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65  m xMalloc or xRe
10a30 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f  alloc.  The allo
10a40 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73  cated size.** is
10a50 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74   always at least
10a60 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72   as big as the r
10a70 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75  equested size bu
10a80 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e  t may be larger.
10a90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e  .**.** The xRoun
10aa0 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72  dup method retur
10ab0 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65  ns what would be
10ac0 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
10ad0 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f  ize of.** a memo
10ae0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69  ry allocation gi
10af0 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ven a particular
10b00 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e   requested size.
10b10 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a    Most memory.**
10b20 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
10b30 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  d up memory allo
10b40 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74  cations at least
10b50 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c   to the next mul
10b60 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20  tiple.** of 8.  
10b70 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20  Some allocators 
10b80 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61  round up to a la
10b90 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72  rger multiple or
10ba0 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32   to a power of 2
10bb0 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72  ..** Every memor
10bc0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
10bd0 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74  uest coming in t
10be0 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f  hrough [sqlite3_
10bf0 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20  malloc()].** or 
10c00 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
10c10 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20  ()] first calls 
10c20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52  xRoundup.  If xR
10c30 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30  oundup returns 0
10c40 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65  , .** that cause
10c50 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  s the correspond
10c60 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ing memory alloc
10c70 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a  ation to fail..*
10c80 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d  *.** The xInit m
10c90 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65  ethod initialize
10ca0 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
10cb0 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61  ocator.  For exa
10cc0 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68  mple,.** it migh
10cd0 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  t allocate any r
10ce0 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f  equire mutexes o
10cf0 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74  r initialize int
10d00 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74  ernal data.** st
10d10 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78  ructures.  The x
10d20 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
10d30 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69  is invoked (indi
10d40 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73  rectly) by.** [s
10d50 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10d60 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65  )] and should de
10d70 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73  allocate any res
10d80 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a  ources acquired.
10d90 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68  ** by xInit.  Th
10da0 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74  e pAppData point
10db0 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68  er is used as th
10dc0 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
10dd0 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64   to.** xInit and
10de0 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a   xShutdown..**.*
10df0 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74  * SQLite holds t
10e00 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
10e10 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20  _STATIC_MASTER] 
10e20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e  mutex when it in
10e30 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e  vokes.** the xIn
10e40 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68  it method, so th
10e50 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e  e xInit method n
10e60 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61  eed not be threa
10e70 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78  dsafe.  The.** x
10e80 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
10e90 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66  is only called f
10ea0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  rom [sqlite3_shu
10eb0 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64  tdown()] so it d
10ec0 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20  oes.** not need 
10ed0 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65  to be threadsafe
10ee0 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c   either.  For al
10ef0 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c  l other methods,
10f00 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73   SQLite.** holds
10f10 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
10f20 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d  EX_STATIC_MEM] m
10f30 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20  utex as long as 
10f40 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  the.** [SQLITE_C
10f50 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
10f60 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
10f70 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ption is turned 
10f80 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20  on (which.** it 
10f90 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61  is by default) a
10fa0 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64  nd so the method
10fb0 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  s are automatica
10fc0 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a  lly serialized..
10fd0 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b  ** However, if [
10fe0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
10ff0 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61  MSTATUS] is disa
11000 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f  bled, then the o
11010 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20  ther.** methods 
11020 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
11030 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20  fe or else make 
11040 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67  their own arrang
11050 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65  ements for.** se
11060 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a  rialization..**.
11070 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  ** SQLite will n
11080 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69  ever invoke xIni
11090 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  t() more than on
110a0 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e  ce without an in
110b0 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c  tervening.** cal
110c0 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29  l to xShutdown()
110d0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
110e0 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
110f0 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
11100 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  mem_methods;.str
11110 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
11120 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64  methods {.  void
11130 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74   *(*xMalloc)(int
11140 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65  );         /* Me
11150 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
11160 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
11170 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64  id (*xFree)(void
11180 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  *);          /* 
11190 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c  Free a prior all
111a0 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  ocation */.  voi
111b0 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76  d *(*xRealloc)(v
111c0 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52  oid*,int);  /* R
111d0 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74  esize an allocat
111e0 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
111f0 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Size)(void*);   
11200 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72          /* Retur
11210 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e  n the size of an
11220 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
11230 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29   int (*xRoundup)
11240 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20  (int);          
11250 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75  /* Round up requ
11260 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f  est size to allo
11270 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20  cation size */. 
11280 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f   int (*xInit)(vo
11290 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
112a0 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68  /* Initialize th
112b0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
112c0 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  or */.  void (*x
112d0 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29  Shutdown)(void*)
112e0 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74  ;      /* Deinit
112f0 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
11300 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
11310 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
11320 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
11330 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78  /* Argument to x
11340 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74  Init() and xShut
11350 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  down() */.};../*
11360 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
11370 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
11380 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
11390 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   {configuration 
113a0 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68  option}.**.** Th
113b0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
113c0 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
113d0 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
113e0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
113f0 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
11400 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
11410 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
11420 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
11430 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
11440 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
11450 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
11460 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
11470 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
11480 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
11490 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
114a0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
114b0 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
114c0 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
114d0 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
114e0 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
114f0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
11500 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
11510 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
11520 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
11530 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
11540 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
11550 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
11560 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
11570 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
11580 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
11590 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
115a0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
115b0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
115c0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
115d0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
115e0 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ETHREAD]] <dt>SQ
115f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
11600 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  LETHREAD</dt>.**
11610 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
11620 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
11630 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
11640 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
11650 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
11660 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65   mode] to Single
11670 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
11680 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
11690 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
116a0 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53  exing and puts S
116b0 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64  QLite into a mod
116c0 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f  e where it can o
116d0 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62  nly be used.** b
116e0 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
116f0 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  d.   ^If SQLite 
11700 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
11710 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
11720 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
11730 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
11740 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
11750 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
11760 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
11770 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b   to change the [
11780 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
11790 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74  from its default
117a0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e  .** value of Sin
117b0 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73  gle-thread and s
117c0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
117d0 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
117e0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
117f0 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
11800 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
11810 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
11820 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  D.** configurati
11830 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
11840 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
11850 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
11860 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
11870 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
11880 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
11890 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
118a0 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
118b0 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
118c0 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
118d0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
118e0 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e  to Multi-thread.
118f0 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
11900 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
11910 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61   mutexing on [da
11920 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11930 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
11940 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
11950 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  cts..** The appl
11960 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f  ication is respo
11970 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61  nsible for seria
11980 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f  lizing access to
11990 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
119a0 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
119b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
119c0 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72  nts].  But other
119d0 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
119e0 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20  enabled so that 
119f0 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73  SQLite will be s
11a00 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20  afe to use in a 
11a10 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a  multi-threaded.*
11a20 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73  * environment as
11a30 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
11a40 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20  threads attempt 
11a50 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a  to use the same.
11a60 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
11a70 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20  nection] at the 
11a80 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20  same time.  ^If 
11a90 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
11aa0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
11ab0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
11ac0 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
11ad0 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
11ae0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
11af0 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
11b00 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
11b10 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20  he Multi-thread 
11b20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
11b30 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
11b40 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
11b50 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
11b60 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
11b70 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
11b80 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
11b90 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74  HREAD configurat
11ba0 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
11bb0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11bc0 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
11bd0 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
11be0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
11bf0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
11c00 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
11c10 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
11c20 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
11c30 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
11c40 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
11c50 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e  o Serialized. In
11c60 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
11c70 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
11c80 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
11c90 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
11ca0 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
11cb0 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
11cc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
11cd0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
11ce0 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
11cf0 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
11d00 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
11d10 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
11d20 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
11d30 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
11d40 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
11d50 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
11d60 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
11d70 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
11d80 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
11d90 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
11da0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
11db0 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
11dc0 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
11dd0 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
11de0 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
11df0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
11e00 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
11e10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
11e20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
11e30 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
11e40 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   time..** ^If SQ
11e50 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
11e60 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
11e70 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
11e80 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
11e90 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
11ea0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
11eb0 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
11ec0 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
11ed0 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   Serialized [thr
11ee0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
11ef0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
11f00 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
11f10 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
11f20 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
11f30 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
11f40 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
11f50 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
11f60 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
11f70 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
11f80 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  G_MALLOC]] <dt>S
11f90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
11fa0 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
11fb0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
11fc0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
11fd0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
11fe0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
11ff0 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
12000 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
12010 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
12020 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
12030 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
12040 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
12050 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
12060 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
12070 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
12080 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65  ace of.** the me
12090 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
120a0 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
120b0 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53  nto SQLite.)^ ^S
120c0 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69  QLite makes.** i
120d0 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
120e0 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65  opy of the conte
120f0 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
12100 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
12110 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66  structure.** bef
12120 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ore the [sqlite3
12130 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20  _config()] call 
12140 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a  returns.</dd>.**
12150 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12160 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20  FIG_GETMALLOC]] 
12170 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
12180 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  G_GETMALLOC</dt>
12190 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
121a0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
121b0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
121c0 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
121d0 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
121e0 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
121f0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
12200 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
12210 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
12220 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
12230 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
12240 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
12250 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20   defined memory 
12260 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
12270 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
12280 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
12290 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
122a0 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  e default memory
122b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
122c0 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
122d0 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75  rapper that simu
122e0 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61  lations memory a
122f0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72  llocation failur
12300 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d  e or.** tracks m
12310 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72  emory usage, for
12320 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a   example. </dd>.
12330 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
12340 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
12350 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12360 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64  FIG_MEMSTATUS</d
12370 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
12380 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69   option takes si
12390 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
123a0 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72   type int, inter
123b0 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20  preted as a .** 
123c0 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65  boolean, which e
123d0 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
123e0 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  es the collectio
123f0 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  n of memory allo
12400 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69  cation .** stati
12410 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65  stics. ^(When me
12420 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12430 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
12440 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a  isabled, the .**
12450 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74   following SQLit
12460 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63  e interfaces bec
12470 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f  ome non-operatio
12480 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a  nal:.**   <ul>.*
12490 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
124a0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
124b0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
124c0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
124d0 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  ater()].**   <li
124e0 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  > [sqlite3_soft_
124f0 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a  heap_limit64()].
12500 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
12510 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20  e3_status()].** 
12520 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65    </ul>)^.** ^Me
12530 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12540 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65  statistics are e
12550 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
12560 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20  t unless SQLite 
12570 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  is.** compiled w
12580 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  ith [SQLITE_DEFA
12590 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30  ULT_MEMSTATUS]=0
125a0 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d   in which case m
125b0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
125c0 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
125d0 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
125e0 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e  efault..** </dd>
125f0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12600 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d  CONFIG_SCRATCH]]
12610 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12620 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a  IG_SCRATCH</dt>.
12630 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
12640 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
12650 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
12660 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
12670 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a  e can use for.**
12680 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e   scratch memory.
12690 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65    There are thre
126a0 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20  e arguments:  A 
126b0 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74  pointer an 8-byt
126c0 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d  e.** aligned mem
126d0 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20  ory buffer from 
126e0 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63  which the scratc
126f0 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69  h allocations wi
12700 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20  ll be.** drawn, 
12710 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
12720 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
12730 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ion (sz),.** and
12740 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
12750 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61  ber of scratch a
12760 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20  llocations (N). 
12770 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d   The sz.** argum
12780 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75  ent must be a mu
12790 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a  ltiple of 16..**
127a0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
127b0 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f  ent must be a po
127c0 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79  inter to an 8-by
127d0 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65  te aligned buffe
127e0 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  r.** of at least
127f0 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
12800 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  emory..** ^SQLit
12810 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f  e will use no mo
12820 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72 61  re than two scra
12830 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20  tch buffers per 
12840 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e  thread.  So.** N
12850 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74   should be set t
12860 6f 20 74 77 69 63 65 20 74 68 65 20 65 78 70 65  o twice the expe
12870 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  cted maximum num
12880 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 0a  ber of threads..
12890 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
128a0 6e 65 76 65 72 20 72 65 71 75 69 72 65 20 61 20  never require a 
128b0 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74  scratch buffer t
128c0 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e  hat is more than
128d0 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20   6.** times the 
128e0 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69  database page si
128f0 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e  ze. ^If SQLite n
12900 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74  eeds needs addit
12910 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68  ional.** scratch
12920 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77   memory beyond w
12930 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
12940 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72  by this configur
12950 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68  ation option, th
12960 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  en .** [sqlite3_
12970 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62  malloc()] will b
12980 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
12990 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64   the memory need
129a0 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ed.</dd>.**.** [
129b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
129c0 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53  AGECACHE]] <dt>S
129d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
129e0 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ECACHE</dt>.** <
129f0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
12a00 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
12a10 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
12a20 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  r that SQLite ca
12a30 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65  n use for.** the
12a40 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63   database page c
12a50 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65  ache with the de
12a60 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 65  fault page cache
12a70 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
12a80 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69    .** This confi
12a90 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  guration should 
12aa0 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61  not be used if a
12ab0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
12ac0 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63  fine page.** cac
12ad0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
12ae0 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e  n is loaded usin
12af0 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  g the SQLITE_CON
12b00 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69  FIG_PCACHE2 opti
12b10 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  on..** There are
12b20 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
12b30 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a   to this option:
12b40 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d   A pointer to 8-
12b50 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20  byte aligned.** 
12b60 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65  memory, the size
12b70 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75   of each page bu
12b80 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74  ffer (sz), and t
12b90 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67  he number of pag
12ba0 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73  es (N)..** The s
12bb0 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  z argument shoul
12bc0 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66  d be the size of
12bd0 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74   the largest dat
12be0 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61  abase page.** (a
12bf0 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65   power of two be
12c00 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32  tween 512 and 32
12c10 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74  768) plus a litt
12c20 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 63  le extra for eac
12c30 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72  h.** page header
12c40 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68 65 61  .  ^The page hea
12c50 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 74  der size is 20 t
12c60 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65 6e  o 40 bytes depen
12c70 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68  ding on.** the h
12c80 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72 65  ost architecture
12c90 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65  .  ^It is harmle
12ca0 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74  ss, apart from t
12cb0 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79  he wasted memory
12cc0 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20  ,.** to make sz 
12cd0 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72  a little too lar
12ce0 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ge.  The first.*
12cf0 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  * argument shoul
12d00 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c  d point to an al
12d10 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c  location of at l
12d20 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20  east sz*N bytes 
12d30 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53  of memory..** ^S
12d40 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
12d50 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64  he memory provid
12d60 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
12d70 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69  argument to sati
12d80 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72  sfy its.** memor
12d90 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20  y needs for the 
12da0 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68  first N pages th
12db0 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61  at it adds to ca
12dc0 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69  che.  ^If additi
12dd0 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63  onal.** page cac
12de0 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65  he memory is nee
12df0 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ded beyond what 
12e00 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
12e10 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  his option, then
12e20 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20  .** SQLite goes 
12e30 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
12e40 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64  oc()] for the ad
12e50 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65  ditional storage
12e60 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70   space..** The p
12e70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69  ointer in the fi
12e80 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
12e90 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20  t.** be aligned 
12ea0 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75  to an 8-byte bou
12eb0 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75  ndary or subsequ
12ec0 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20  ent behavior of 
12ed0 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62  SQLite.** will b
12ee0 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64  e undefined.</dd
12ef0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12f00 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c  _CONFIG_HEAP]] <
12f10 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12f20 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _HEAP</dt>.** <d
12f30 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
12f40 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
12f50 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
12f60 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
12f70 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c  l use.** for all
12f80 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20   of its dynamic 
12f90 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12fa0 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74  n needs beyond t
12fb0 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a  hose provided.**
12fc0 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f   for by [SQLITE_
12fd0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20  CONFIG_SCRATCH] 
12fe0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  and [SQLITE_CONF
12ff0 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
13000 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65  * There are thre
13010 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20  e arguments: An 
13020 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70  8-byte aligned p
13030 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
13040 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d  mory,.** the num
13050 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
13060 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  the memory buffe
13070 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d  r, and the minim
13080 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
13090 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ze..** ^If the f
130a0 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
130b0 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
130c0 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  ) is NULL, then 
130d0 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a  SQLite reverts.*
130e0 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64  * to using its d
130f0 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
13100 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73  locator (the sys
13110 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70  tem malloc() imp
13120 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a  lementation),.**
13130 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69   undoing any pri
13140 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  or invocation of
13150 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
13160 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68  MALLOC].  ^If th
13170 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  e.** memory poin
13180 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ter is not NULL 
13190 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49  and either [SQLI
131a0 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
131b0 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  3] or.** [SQLITE
131c0 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d  _ENABLE_MEMSYS5]
131d0 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68   are defined, th
131e0 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69  en the alternati
131f0 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  ve memory.** all
13200 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65  ocator is engage
13210 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20  d to handle all 
13220 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72  of SQLites memor
13230 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
13240 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ds..** The first
13250 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
13260 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75  mory pointer) mu
13270 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  st be aligned to
13280 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f   an 8-byte.** bo
13290 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
132a0 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
132b0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
132c0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
132d0 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
132e0 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70  tion size is cap
132f0 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65  ped at 2**12. Re
13300 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a  asonable values.
13310 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d  ** for the minim
13320 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
13330 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f  ze are 2**5 thro
13340 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a  ugh 2**8.</dd>.*
13350 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13360 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74  NFIG_MUTEX]] <dt
13370 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
13380 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
13390 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
133a0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
133b0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
133c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
133d0 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
133e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
133f0 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
13400 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75  cture.  The argu
13410 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a  ment specifies.*
13420 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  * alternative lo
13430 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f  w-level mutex ro
13440 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
13450 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68  d in place.** th
13460 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  e mutex routines
13470 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
13480 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  te.)^  ^SQLite m
13490 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
134a0 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66  he.** content of
134b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
134c0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
134d0 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68  ucture before th
134e0 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  e call to.** [sq
134f0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
13500 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c  returns. ^If SQL
13510 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
13520 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
13530 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
13540 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
13550 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
13560 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
13570 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
13580 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
13590 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
135a0 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
135b0 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
135c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
135d0 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
135e0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
135f0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13600 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
13610 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
13620 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  R].</dd>.**.** [
13630 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
13640 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  ETMUTEX]] <dt>SQ
13650 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
13660 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
13670 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
13680 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
13690 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
136a0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
136b0 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
136c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
136d0 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
136e0 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b  cture.  The.** [
136f0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
13700 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
13710 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
13720 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
13730 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72   defined mutex r
13740 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68  outines.)^.** Th
13750 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  is option can be
13760 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61   used to overloa
13770 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75  d the default mu
13780 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  tex allocation.*
13790 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
137a0 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74  a wrapper used t
137b0 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73  o track mutex us
137c0 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61  age for performa
137d0 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67  nce.** profiling
137e0 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72   or testing, for
137f0 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20   example.   ^If 
13800 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
13810 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
13820 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
13830 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
13840 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
13850 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
13860 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
13870 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
13880 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
13890 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
138a0 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
138b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
138c0 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
138d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
138e0 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
138f0 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
13900 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
13910 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
13920 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13930 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d  NFIG_LOOKASIDE]]
13940 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13950 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
13960 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
13970 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
13980 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  o arguments that
13990 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
139a0 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79  efault.** memory
139b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20   allocation for 
139c0 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
139d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f  mory allocator o
139e0 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62  n each.** [datab
139f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
13a00 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75    The first argu
13a10 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
13a20 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
13a30 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
13a40 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
13a50 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
13a60 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63  f.** slots alloc
13a70 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74  ated to each dat
13a80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13a90 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69  .)^  ^(This opti
13aa0 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c  on sets the.** <
13ab0 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f  i>default</i> lo
13ac0 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68  okaside size. Th
13ad0 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  e [SQLITE_DBCONF
13ae0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a  IG_LOOKASIDE].**
13af0 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65   verb to [sqlite
13b00 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63  3_db_config()] c
13b10 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68  an be used to ch
13b20 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69  ange the lookasi
13b30 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  de.** configurat
13b40 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
13b50 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e  l connections.)^
13b60 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
13b70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
13b80 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  CHE2]] <dt>SQLIT
13b90 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
13ba0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
13bb0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
13bc0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
13bd0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
13be0 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20  ointer to.** an 
13bf0 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
13c00 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
13c10 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73  .  This object s
13c20 70 65 63 69 66 69 65 73 20 74 68 65 20 69 6e 74  pecifies the int
13c30 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63  erface.** to a c
13c40 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65  ustom page cache
13c50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
13c60 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
13c70 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
13c80 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73  ** object and us
13c90 65 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63  es it for page c
13ca0 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ache memory allo
13cb0 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a  cations.</dd>.**
13cc0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13cd0 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d  FIG_GETPCACHE2]]
13ce0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13cf0 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64  IG_GETPCACHE2</d
13d00 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
13d10 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
13d20 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
13d30 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
13d40 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71  ter to an.** [sq
13d50 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
13d60 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
13d70 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66  SQLite copies of
13d80 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
13d90 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
13da0 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74  mentation into t
13db0 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f  hat object.)^ </
13dc0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13dd0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20  TE_CONFIG_LOG]] 
13de0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13df0 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  G_LOG</dt>.** <d
13e00 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d> The SQLITE_CO
13e10 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
13e20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69  is used to confi
13e30 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a  gure the SQLite.
13e40 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72  ** global [error
13e50 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20   log]..** (^The 
13e60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
13e70 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  G option takes t
13e80 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20  wo arguments: a 
13e90 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20  pointer to a.** 
13ea0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
13eb0 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f  call signature o
13ec0 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  f void(*)(void*,
13ed0 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  int,const char*)
13ee0 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e  , .** and a poin
13ef0 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66  ter to void. ^If
13f00 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
13f10 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
13f20 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f  L, it is.** invo
13f30 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ked by [sqlite3_
13f40 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73  log()] to proces
13f50 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65  s each logging e
13f60 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
13f70 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  * function point
13f80 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20  er is NULL, the 
13f90 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
13fa0 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65  interface become
13fb0 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54  s a no-op..** ^T
13fc0 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20  he void pointer 
13fd0 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f  that is the seco
13fe0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53  nd argument to S
13ff0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
14000 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68   is.** passed th
14010 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
14020 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
14030 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
14040 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
14050 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65  * function whene
14060 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f  ver that functio
14070 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  n is invoked.  ^
14080 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
14090 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c  eter to.** the l
140a0 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69  ogger function i
140b0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
140c0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
140d0 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  to the correspon
140e0 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ding.** [sqlite3
140f0 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64  _log()] call and
14100 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
14110 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64  be a [result cod
14120 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74  e] or an.** [ext
14130 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
14140 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  e].  ^The third 
14150 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64  parameter passed
14160 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69   to the logger i
14170 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65  s.** log message
14180 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e   after formattin
14190 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73  g via [sqlite3_s
141a0 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54  nprintf()]..** T
141b0 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e  he SQLite loggin
141c0 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  g interface is n
141d0 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68  ot reentrant; th
141e0 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
141f0 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79  n.** supplied by
14200 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
14210 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65   must not invoke
14220 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
14230 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d  rface..** In a m
14240 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70  ulti-threaded ap
14250 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61  plication, the a
14260 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
14270 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
14280 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68  ction must be th
14290 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a  readsafe. </dd>.
142a0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
142b0 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e  ONFIG_URI]] <dt>
142c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
142d0 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 69 73 20  I.** <dd>^(This 
142e0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
142f0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
14300 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66 20 6e  f type int. If n
14310 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a 2a  on-zero, then.**
14320 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
14330 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65   globally enable
14340 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65  d. If the parame
14350 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 68 65  ter is zero, the
14360 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a 2a  n URI handling.*
14370 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69  * is globally di
14380 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52  sabled.)^ ^If UR
14390 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
143a0 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20  obally enabled, 
143b0 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a  all filenames.**
143c0 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
143d0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
143e0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
143f0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
14400 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69  6()] or.** speci
14410 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  fied as part of 
14420 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64  [ATTACH] command
14430 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
14440 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72  d as URIs, regar
14450 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74  dless.** of whet
14460 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b  her or not the [
14470 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
14480 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
14490 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  n the database.*
144a0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  * connection is 
144b0 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69  opened. ^If it i
144c0 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
144d0 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61  led, filenames a
144e0 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72  re.** only inter
144f0 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69  preted as URIs i
14500 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  f the SQLITE_OPE
14510 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65  N_URI flag is se
14520 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61  t when the.** da
14530 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14540 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42  n is opened. ^(B
14550 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68  y default, URI h
14560 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
14570 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e  lly.** disabled.
14580 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
14590 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65  ue may be change
145a0 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77  d by compiling w
145b0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
145c0 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62  TE_USE_URI] symb
145d0 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a  ol defined.)^.**
145e0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
145f0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
14600 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51  EX_SCAN]] <dt>SQ
14610 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
14620 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a  RING_INDEX_SCAN.
14630 2a 2a 20 3c 64 64 3e 5e 54 68 69 73 20 6f 70 74  ** <dd>^This opt
14640 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
14650 6c 65 20 69 6e 74 65 67 65 72 20 61 72 67 75 6d  le integer argum
14660 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74  ent which is int
14670 65 72 70 72 65 74 65 64 20 61 73 0a 2a 2a 20 61  erpreted as.** a
14680 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65   boolean in orde
14690 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  r to enable or d
146a0 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f  isable the use o
146b0 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63  f covering indic
146c0 65 73 20 66 6f 72 0a 2a 2a 20 66 75 6c 6c 20 74  es for.** full t
146d0 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68  able scans in th
146e0 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65  e query optimize
146f0 72 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74  r.  ^The default
14700 20 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 65   setting is dete
14710 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65  rmined.** by the
14720 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43   [SQLITE_ALLOW_C
14730 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
14740 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  AN] compile-time
14750 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22   option, or is "
14760 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63  on".** if that c
14770 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
14780 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a  on is omitted..*
14790 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f  * The ability to
147a0 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65   disable the use
147b0 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64   of covering ind
147c0 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61  ices for full ta
147d0 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20  ble scans.** is 
147e0 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63  because some inc
147f0 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c  orrectly coded l
14800 65 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f  egacy applicatio
14810 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63  ns might malfunc
14820 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65  tion.** when the
14830 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73   optimization is
14840 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69   enabled.  Provi
14850 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79  ding the ability
14860 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74   to.** disable t
14870 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20  he optimization 
14880 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72  allows the older
14890 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 74  , buggy applicat
148a0 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b  ion code to work
148b0 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e  .** without chan
148c0 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77  ge even with new
148d0 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
148e0 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  QLite..**.** [[S
148f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
14900 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43  CHE]] [[SQLITE_C
14910 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d  ONFIG_GETPCACHE]
14920 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
14930 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e  CONFIG_PCACHE an
14940 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  d SQLITE_CONFIG_
14950 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64  GETPCACHE.** <dd
14960 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20  > These options 
14970 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64  are obsolete and
14980 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
14990 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e  sed by new code.
149a0 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74  .** They are ret
149b0 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61  ained for backwa
149c0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
149d0 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f  y but are now no
149e0 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  -ops..** </dd>.*
149f0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
14a00 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a  NFIG_SQLLOG]].**
14a10 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14a20 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64  IG_SQLLOG.** <dd
14a30 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  >This option is 
14a40 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
14a50 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70  f sqlite is comp
14a60 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
14a70 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
14a80 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63  SQLLOG] pre-proc
14a90 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69  essor macro defi
14aa0 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 61  ned. The first a
14ab0 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a  rgument should.*
14ac0 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  * be a pointer t
14ad0 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20  o a function of 
14ae0 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69  type void(*)(voi
14af0 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73  d*,sqlite3*,cons
14b00 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a  t char*, int)..*
14b10 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f  * The second sho
14b20 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20 28  uld be of type (
14b30 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c  void*). The call
14b40 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
14b50 62 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a  by the library.*
14b60 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70 61 72  * in three separ
14b70 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ate circumstance
14b80 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  s, identified by
14b90 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65   the value passe
14ba0 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72  d as the.** four
14bb0 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66  th parameter. If
14bc0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
14bd0 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e  meter is 0, then
14be0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
14bf0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73  nnection.** pass
14c00 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
14c10 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75   argument has ju
14c20 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20  st been opened. 
14c30 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
14c40 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20  nt.** points to 
14c50 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e  a buffer contain
14c60 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  ing the name of 
14c70 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73  the main databas
14c80 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a  e file. If the.*
14c90 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  * fourth paramet
14ca0 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68  er is 1, then th
14cb0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
14cc0 74 68 61 74 20 74 68 65 20 74 68 69 72 64 20 70  that the third p
14cd0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e  arameter.** poin
14ce0 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62  ts to has just b
14cf0 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72  een executed. Or
14d00 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74 68 20  , if the fourth 
14d10 70 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20  parameter is 2, 
14d20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e  then.** the conn
14d30 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73  ection being pas
14d40 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
14d50 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 62  d parameter is b
14d60 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65  eing closed. The
14d70 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65  .** third parame
14d80 74 65 72 20 69 73 20 70 61 73 73 65 64 20 4e 55  ter is passed NU
14d90 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e  LL In this case.
14da0 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20    An example of 
14db0 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f  using this.** co
14dc0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
14dd0 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69  on can be seen i
14de0 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c  n the "test_sqll
14df0 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c  og.c" source fil
14e00 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f  e in.** the cano
14e10 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75  nical SQLite sou
14e20 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a  rce tree.</dd>.*
14e30 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
14e40 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d  NFIG_MMAP_SIZE]]
14e50 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
14e60 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a  ONFIG_MMAP_SIZE.
14e70 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43  ** <dd>^SQLITE_C
14e80 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20  ONFIG_MMAP_SIZE 
14e90 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74  takes two 64-bit
14ea0 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65   integer (sqlite
14eb0 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a  3_int64) values.
14ec0 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68 65 20  ** that are the 
14ed0 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a  default mmap siz
14ee0 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66  e limit (the def
14ef0 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72  ault setting for
14f00 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70  .** [PRAGMA mmap
14f10 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20  _size]) and the 
14f20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20  maximum allowed 
14f30 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e  mmap size limit.
14f40 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
14f50 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20   setting can be 
14f60 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 65 61  overridden by ea
14f70 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
14f80 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  ection using.** 
14f90 65 69 74 68 65 72 20 74 68 65 20 5b 50 52 41 47  either the [PRAG
14fa0 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f  MA mmap_size] co
14fb0 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69  mmand, or by usi
14fc0 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ng the.** [SQLIT
14fd0 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
14fe0 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e  E] file control.
14ff0 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20    ^(The maximum 
15000 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a  allowed mmap siz
15010 65 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 63  e.** cannot be c
15020 68 61 6e 67 65 64 20 61 74 20 72 75 6e 2d 74 69  hanged at run-ti
15030 6d 65 2e 20 20 4e 6f 72 20 6d 61 79 20 74 68 65  me.  Nor may the
15040 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64   maximum allowed
15050 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 65 78   mmap size.** ex
15060 63 65 65 64 20 74 68 65 20 63 6f 6d 70 69 6c 65  ceed the compile
15070 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d  -time maximum mm
15080 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 74  ap size set by t
15090 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41  he.** [SQLITE_MA
150a0 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d  X_MMAP_SIZE] com
150b0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
150c0 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65  .)^.** ^If eithe
150d0 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  r argument to th
150e0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67  is option is neg
150f0 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74  ative, then that
15100 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
15110 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63  changed to its c
15120 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61  ompile-time defa
15130 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ult..**.** [[SQL
15140 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
15150 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c  _HEAPSIZE]].** <
15160 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15170 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a  _WIN32_HEAPSIZE.
15180 2a 2a 20 3c 64 64 3e 5e 54 68 69 73 20 6f 70 74  ** <dd>^This opt
15190 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
151a0 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20  lable if SQLite 
151b0 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  is compiled for 
151c0 57 69 6e 64 6f 77 73 0a 2a 2a 20 77 69 74 68 20  Windows.** with 
151d0 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33  the [SQLITE_WIN3
151e0 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72  2_MALLOC] pre-pr
151f0 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65  ocessor macro de
15200 66 69 6e 65 64 2e 0a 2a 2a 20 53 51 4c 49 54 45  fined..** SQLITE
15210 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
15220 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33  APSIZE takes a 3
15230 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69  2-bit unsigned i
15240 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20  nteger value.** 
15250 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74  that specifies t
15260 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
15270 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20 68  of the created h
15280 65 61 70 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  eap..** </dl>.*/
15290 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
152a0 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
152b0 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a  EAD  1  /* nil *
152c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
152d0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
152e0 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20  EAD   2  /* nil 
152f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15300 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
15310 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c  ZED    3  /* nil
15320 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15330 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
15340 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71          4  /* sq
15350 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
15360 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
15370 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
15380 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20  ALLOC     5  /* 
15390 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
153a0 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
153b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
153c0 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f  RATCH       6  /
153d0 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
153e0 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
153f0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15400 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
15410 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
15420 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
15430 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15440 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
15450 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
15460 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
15470 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15480 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
15490 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
154a0 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
154b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
154c0 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
154d0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
154e0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
154f0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15500 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
15510 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
15520 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
15530 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51  /* previously SQ
15540 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e  LITE_CONFIG_CHUN
15550 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20  KALLOC 12 which 
15560 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a  is now unused. *
15570 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  / .#define SQLIT
15580 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
15590 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74  DE    13  /* int
155a0 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
155b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
155c0 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f  ACHE       14  /
155d0 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69  * no-op */.#defi
155e0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
155f0 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35  _GETPCACHE    15
15600 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
15610 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15620 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20  FIG_LOG         
15630 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76   16  /* xFunc, v
15640 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
15650 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
15660 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f  I          17  /
15670 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
15680 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
15690 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20  CACHE2      18  
156a0 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
156b0 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
156c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
156d0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20  NFIG_GETPCACHE2 
156e0 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33    19  /* sqlite3
156f0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
15700 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
15710 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
15720 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32  ING_INDEX_SCAN 2
15730 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  0  /* int */.#de
15740 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15750 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20  IG_SQLLOG       
15760 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20  21  /* xSqllog, 
15770 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
15780 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
15790 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20  MAP_SIZE    22  
157a0 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  /* sqlite3_int64
157b0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
157c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
157d0 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
157e0 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20  EAPSIZE      23 
157f0 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f   /* int nByte */
15800 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
15810 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
15820 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74  ction Configurat
15830 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a  ion Options.**.*
15840 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
15850 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
15860 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
15870 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
15880 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
15890 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
158a0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
158b0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64  o the [sqlite3_d
158c0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  b_config()] inte
158d0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
158e0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
158f0 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
15900 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
15910 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
15920 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
15930 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
15940 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
15950 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
15960 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
15970 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
15980 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
15990 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
159a0 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
159b0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
159c0 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20  l worked.  ^The 
159d0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
159e0 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
159f0 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
15a00 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
15a10 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
15a20 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
15a30 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
15a40 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
15a50 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
15a60 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
15a70 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
15a80 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
15a90 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
15aa0 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64  n takes three ad
15ab0 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
15ac0 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
15ad0 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61  e the .** [looka
15ae0 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
15af0 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61  cator] configura
15b00 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61  tion for the [da
15b10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15b20 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  n]..** ^The firs
15b30 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20  t argument (the 
15b40 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
15b50 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
15b60 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a  onfig()] is a.**
15b70 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
15b80 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75  mory buffer to u
15b90 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65  se for lookaside
15ba0 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65   memory..** ^The
15bb0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
15bc0 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45  after the SQLITE
15bd0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
15be0 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20  IDE verb.** may 
15bf0 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68  be NULL in which
15c00 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c   case SQLite wil
15c10 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a  l allocate the.*
15c20 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  * lookaside buff
15c30 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20  er itself using 
15c40 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
15c50 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  )]. ^The second 
15c60 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
15c70 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
15c80 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
15c90 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69   slot.  ^The thi
15ca0 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
15cb0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
15cc0 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65  slots.  The size
15cd0 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69   of the buffer i
15ce0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
15cf0 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65  ment must be gre
15d00 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20  ater than.** or 
15d10 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f  equal to the pro
15d20 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f  duct of the seco
15d30 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67  nd and third arg
15d40 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66  uments.  The buf
15d50 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61  fer.** must be a
15d60 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
15d70 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e  yte boundary.  ^
15d80 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  If the second ar
15d90 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c  gument to.** SQL
15da0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
15db0 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20  KASIDE is not a 
15dc0 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69  multiple of 8, i
15dd0 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  t is internally.
15de0 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20  ** rounded down 
15df0 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c  to the next smal
15e00 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  ler multiple of 
15e10 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73  8.  ^(The lookas
15e20 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f  ide memory.** co
15e30 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
15e40 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
15e50 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62  ction can only b
15e60 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74  e changed when t
15e70 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  hat.** connectio
15e80 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  n is not current
15e90 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69  ly using lookasi
15ea0 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e  de memory, or in
15eb0 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20   other words.** 
15ec0 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e  when the "curren
15ed0 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65  t value" returne
15ee0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
15ef0 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53  _db_status](D,[S
15f00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
15f10 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20  KASIDE],...) is 
15f20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  zero..** Any att
15f30 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74  empt to change t
15f40 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
15f50 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ory configuratio
15f60 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65  n when lookaside
15f70 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e  .** memory is in
15f80 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20   use leaves the 
15f90 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e  configuration un
15fa0 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75  changed and retu
15fb0 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rns .** [SQLITE_
15fc0 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  BUSY].)^</dd>.**
15fd0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
15fe0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
15ff0 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  KEY</dt>.** <dd>
16000 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
16010 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
16020 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65  or disable the e
16030 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a  nforcement of.**
16040 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f   [foreign key co
16050 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65  nstraints].  The
16060 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
16070 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
16080 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
16090 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
160a0 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
160b0 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
160c0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c   FK enforcement,
160d0 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
160e0 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63  enable FK enforc
160f0 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76  ement or negativ
16100 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e  e to leave FK en
16110 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63  forcement.** unc
16120 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63  hanged.  The sec
16130 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
16140 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
16150 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
16160 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
16170 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
16180 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20  cate whether FK 
16190 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f  enforcement is o
161a0 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c  ff or on.** foll
161b0 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
161c0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
161d0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
161e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
161f0 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
16200 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  he FK enforcemen
16210 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  t setting is not
16220 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
16230 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
16240 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
16250 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f  ENABLE_TRIGGER</
16260 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
16270 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
16280 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
16290 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52  sable [CREATE TR
162a0 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73  IGGER | triggers
162b0 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  ]..** There shou
162c0 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
162d0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
162e0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
162f0 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
16300 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
16310 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65  o disable trigge
16320 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  rs,.** positive 
16330 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65  to enable trigge
16340 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  rs or negative t
16350 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  o leave the sett
16360 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  ing unchanged..*
16370 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
16380 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
16390 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
163a0 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
163b0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
163c0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
163d0 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61  ether triggers a
163e0 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  re disabled or e
163f0 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nabled.** follow
16400 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
16410 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
16420 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
16430 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
16440 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
16450 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67   trigger setting
16460 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
16470 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
16480 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
16490 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
164a0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
164b0 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69      1001  /* voi
164c0 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  d* int int */.#d
164d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
164e0 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
164f0 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69  Y     1002  /* i
16500 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
16510 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
16520 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
16530 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20  R  1003  /* int 
16540 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20  int* */.../*.** 
16550 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
16560 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
16570 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
16580 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
16590 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
165a0 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75  sult_codes() rou
165b0 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
165c0 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20  disables the.** 
165d0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
165e0 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20   codes] feature 
165f0 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20  of SQLite. ^The 
16600 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a  extended result.
16610 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73  ** codes are dis
16620 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
16630 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20   for historical 
16640 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
16650 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
16660 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
16670 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  des(sqlite3*, in
16680 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a  t onoff);../*.**
16690 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20   CAPI3REF: Last 
166a0 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a  Insert Rowid.**.
166b0 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69  ** ^Each entry i
166c0 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 20 74 61  n most SQLite ta
166d0 62 6c 65 73 20 28 65 78 63 65 70 74 20 66 6f 72  bles (except for
166e0 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d   [WITHOUT ROWID]
166f0 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20   tables).** has 
16700 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20  a unique 64-bit 
16710 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65  signed.** intege
16720 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65  r key called the
16730 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64   [ROWID | "rowid
16740 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69  "]. ^The rowid i
16750 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62  s always availab
16760 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65  le.** as an unde
16770 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61  clared column na
16780 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20  med ROWID, OID, 
16790 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f  or _ROWID_ as lo
167a0 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e  ng as those.** n
167b0 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73  ames are not als
167c0 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63  o used by explic
167d0 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f  itly declared co
167e0 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68  lumns. ^If.** th
167f0 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f  e table has a co
16800 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e  lumn of type [IN
16810 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
16820 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c  Y] then that col
16830 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65  umn.** is anothe
16840 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20  r alias for the 
16850 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rowid..**.** ^Th
16860 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  e sqlite3_last_i
16870 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 69  nsert_rowid(D) i
16880 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
16890 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
168a0 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 72 65 63  the .** most rec
168b0 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b  ent successful [
168c0 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72  INSERT] into a r
168d0 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76  owid table or [v
168e0 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a  irtual table].**
168f0 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e   on database con
16900 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49  nection D..** ^I
16910 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54  nserts into [WIT
16920 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c  HOUT ROWID] tabl
16930 65 73 20 61 72 65 20 6e 6f 74 20 72 65 63 6f 72  es are not recor
16940 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73  ded..** ^If no s
16950 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
16960 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74  T]s into rowid t
16970 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65 20 65 76  ables.** have ev
16980 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74  er occurred on t
16990 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
169a0 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68  ection D, .** th
169b0 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  en sqlite3_last_
169c0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20  insert_rowid(D) 
169d0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
169e0 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53  .** ^(If an [INS
169f0 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68  ERT] occurs with
16a00 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72 20  in a trigger or 
16a10 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61  within a [virtua
16a20 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68  l table].** meth
16a30 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f  od, then this ro
16a40 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72  utine will retur
16a50 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  n the [rowid] of
16a60 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a   the inserted.**
16a70 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20   row as long as 
16a80 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76  the trigger or v
16a90 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74  irtual table met
16aa0 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  hod is running..
16ab0 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20  ** But once the 
16ac0 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75  trigger or virtu
16ad0 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20  al table method 
16ae0 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20  ends, the value 
16af0 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20  returned .** by 
16b00 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76  this routine rev
16b10 65 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 20  erts to what it 
16b20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 74  was before the t
16b30 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61  rigger or virtua
16b40 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f  l.** table metho
16b50 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a  d began.)^.**.**
16b60 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68   ^An [INSERT] th
16b70 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20  at fails due to 
16b80 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
16b90 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a  lation is not a.
16ba0 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  ** successful [I
16bb0 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20  NSERT] and does 
16bc0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
16bd0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
16be0 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
16bf0 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20  .  ^Thus INSERT 
16c00 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20  OR FAIL, INSERT 
16c10 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52  OR IGNORE, INSER
16c20 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a  T OR ROLLBACK,.*
16c30 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20  * and INSERT OR 
16c40 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68  ABORT make no ch
16c50 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74  anges to the ret
16c60 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
16c70 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65  s.** routine whe
16c80 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f  n their insertio
16c90 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e  n fails.  ^(When
16ca0 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
16cb0 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73  CE.** encounters
16cc0 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
16cd0 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73  olation, it does
16ce0 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a   not fail.  The.
16cf0 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e  ** INSERT contin
16d00 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  ues to completio
16d10 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67  n after deleting
16d20 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65   rows that cause
16d30 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61  d.** the constra
16d40 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49  int problem so I
16d50 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
16d60 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61   will always cha
16d70 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72  nge.** the retur
16d80 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  n value of this 
16d90 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a  interface.)^.**.
16da0 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70  ** ^For the purp
16db0 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75  oses of this rou
16dc0 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54  tine, an [INSERT
16dd0 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  ] is considered 
16de0 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73  to.** be success
16df0 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69  ful even if it i
16e00 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72  s subsequently r
16e10 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a  olled back..**.*
16e20 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
16e30 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f  is accessible to
16e40 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
16e50 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74  via the.** [last
16e60 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20  _insert_rowid() 
16e70 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
16e80 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
16e90 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72  te thread perfor
16ea0 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54  ms a new [INSERT
16eb0 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  ] on the same.**
16ec0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
16ed0 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b  tion while the [
16ee0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
16ef0 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20  ert_rowid()].** 
16f00 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
16f10 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61  ing and thus cha
16f20 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e  nges the last in
16f30 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a  sert [rowid],.**
16f40 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
16f50 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
16f60 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
16f70 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20  _rowid()] is.** 
16f80 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
16f90 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61  d might not equa
16fa0 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64  l either the old
16fb0 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c   or the new.** l
16fc0 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
16fd0 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  d]..*/.sqlite3_i
16fe0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73  nt64 sqlite3_las
16ff0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73  t_insert_rowid(s
17000 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
17010 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74   CAPI3REF: Count
17020 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52   The Number Of R
17030 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a  ows Modified.**.
17040 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
17050 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
17060 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65  mber of database
17070 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20   rows that were 
17080 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e  changed.** or in
17090 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
170a0 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65  d by the most re
170b0 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
170c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a   SQL statement.*
170d0 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61  * on the [databa
170e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
170f0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
17100 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
17110 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67  .** ^(Only chang
17120 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65  es that are dire
17130 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62  ctly specified b
17140 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20  y the [INSERT], 
17150 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20  [UPDATE],.** or 
17160 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
17170 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20  nt are counted. 
17180 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67   Auxiliary chang
17190 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20  es caused by.** 
171a0 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72  triggers or [for
171b0 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
171c0 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  ] are not counte
171d0 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20  d.)^ Use the.** 
171e0 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
171f0 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69  hanges()] functi
17200 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74  on to find the t
17210 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63  otal number of c
17220 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64  hanges.** includ
17230 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73  ing changes caus
17240 65 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61  ed by triggers a
17250 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  nd foreign key a
17260 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ctions..**.** ^C
17270 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
17280 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61   that are simula
17290 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45  ted by an [INSTE
172a0 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a  AD OF trigger].*
172b0 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  * are not counte
172c0 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61  d.  Only real ta
172d0 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20  ble changes are 
172e0 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  counted..**.** ^
172f0 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20  (A "row change" 
17300 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61  is a change to a
17310 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61   single row of a
17320 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a   single table.**
17330 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e   caused by an IN
17340 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72  SERT, DELETE, or
17350 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e   UPDATE statemen
17360 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a  t.  Rows that.**
17370 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20   are changed as 
17380 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20  side effects of 
17390 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72  [REPLACE] constr
173a0 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c  aint resolution,
173b0 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42  .** rollback, AB
173c0 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20  ORT processing, 
173d0 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72  [DROP TABLE], or
173e0 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a   by any other.**
173f0 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e   mechanisms do n
17400 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65  ot count as dire
17410 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29  ct row changes.)
17420 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67  ^.**.** A "trigg
17430 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61  er context" is a
17440 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74   scope of execut
17450 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20  ion that begins 
17460 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68  and.** ends with
17470 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61   the script of a
17480 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
17490 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a   | trigger]. .**
174a0 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d   Most SQL statem
174b0 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c  ents are.** eval
174c0 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66  uated outside of
174d0 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54   any trigger.  T
174e0 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20  his is the "top 
174f0 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65  level".** trigge
17500 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61  r context.  If a
17510 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66   trigger fires f
17520 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65  rom the top leve
17530 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67  l, a.** new trig
17540 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65  ger context is e
17550 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64  ntered for the d
17560 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20  uration of that 
17570 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20  one.** trigger. 
17580 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65   Subtriggers cre
17590 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20  ate subcontexts 
175a0 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69  for their durati
175b0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  on..**.** ^Calli
175c0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ng [sqlite3_exec
175d0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
175e0 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76  step()] recursiv
175f0 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ely does.** not 
17600 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69  create a new tri
17610 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a  gger context..**
17620 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
17630 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
17640 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20  umber of direct 
17650 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74  row changes in t
17660 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e  he.** most recen
17670 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
17680 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  , or DELETE stat
17690 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
176a0 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72   same.** trigger
176b0 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
176c0 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c  ^Thus, when call
176d0 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20  ed from the top 
176e0 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63  level, this func
176f0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
17700 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  .** number of ch
17710 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
17720 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
17730 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
17740 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20  TE.** that also 
17750 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20  occurred at the 
17760 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69  top level.  ^(Wi
17770 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
17780 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74   a trigger,.** t
17790 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
177a0 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  es() interface c
177b0 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20  an be called to 
177c0 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
177d0 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e  of.** changes in
177e0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
177f0 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
17800 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
17810 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d  DELETE.** statem
17820 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62  ent within the b
17830 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ody of the same 
17840 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65  trigger..** Howe
17850 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20  ver, the number 
17860 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f  returned does no
17870 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65  t include change
17880 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73  s.** caused by s
17890 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65  ubtriggers since
178a0 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69   those have thei
178b0 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e  r own context.)^
178c0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
178d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  the [sqlite3_tot
178e0 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  al_changes()] in
178f0 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
17900 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
17910 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
17920 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
17930 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
17940 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
17950 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
17960 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
17970 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17980 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
17990 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
179a0 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
179b0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
179c0 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69  ed.** is unpredi
179d0 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
179e0 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e  eaningful..*/.in
179f0 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  t sqlite3_change
17a00 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
17a10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f  .** CAPI3REF: To
17a20 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  tal Number Of Ro
17a30 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a  ws Modified.**.*
17a40 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
17a50 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
17a60 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67  ber of row chang
17a70 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e  es caused by [IN
17a80 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54  SERT],.** [UPDAT
17a90 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73  E] or [DELETE] s
17aa0 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20  tatements since 
17ab0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
17ac0 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70  nnection] was op
17ad0 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63  ened..** ^(The c
17ae0 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79  ount returned by
17af0 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
17b00 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65  hanges() include
17b10 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a  s all changes.**
17b20 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54   from all [CREAT
17b30 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
17b40 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e  ger] contexts an
17b50 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62  d changes made b
17b60 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65  y.** [foreign ke
17b70 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65  y actions]. Howe
17b80 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e  ver,.** the coun
17b90 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
17ba0 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20  de changes used 
17bb0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45  to implement [RE
17bc0 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e  PLACE] constrain
17bd0 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61  ts,.** do rollba
17be0 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f  cks or ABORT pro
17bf0 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f  cessing, or [DRO
17c00 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73  P TABLE] process
17c10 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75  ing.  The.** cou
17c20 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  nt does not incl
17c30 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77  ude rows of view
17c40 73 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b  s that fire an [
17c50 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
17c60 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69  er],.** though i
17c70 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46  f the INSTEAD OF
17c80 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63   trigger makes c
17c90 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77  hanges of its ow
17ca0 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73  n, those changes
17cb0 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64   .** are counted
17cc0 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .)^.** ^The sqli
17cd0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
17ce0 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75  s() function cou
17cf0 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65 73 20  nts the changes 
17d00 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68  as soon as.** th
17d10 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  e statement that
17d20 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63   makes them is c
17d30 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74  ompleted (when t
17d40 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e  he statement han
17d50 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64  dle.** is passed
17d60 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
17d70 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
17d80 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a  3_finalize()])..
17d90 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
17da0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  he [sqlite3_chan
17db0 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
17dc0 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
17dd0 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
17de0 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f   and the [total_
17df0 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
17e00 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
17e10 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
17e20 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
17e30 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
17e40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17e50 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
17e60 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
17e70 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
17e80 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a  then the value.*
17e90 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e  * returned is un
17ea0 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
17eb0 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
17ec0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
17ed0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
17ee0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
17ef0 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
17f00 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
17f10 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54  g Query.**.** ^T
17f20 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
17f30 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
17f40 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
17f50 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
17f60 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
17f70 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
17f80 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74  unity. This rout
17f90 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
17fa0 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
17fb0 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
17fc0 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
17fd0 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
17fe0 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
17ff0 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
18000 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
18010 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
18020 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
18030 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  y..**.** ^It is 
18040 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
18050 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
18060 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
18070 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
18080 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
18090 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
180a0 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
180b0 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
180c0 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
180d0 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
180e0 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
180f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
18100 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
18110 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
18120 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
18130 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
18140 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  rns..**.** ^If a
18150 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
18160 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66  is very nearly f
18170 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74  inished at the t
18180 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69  ime when.** sqli
18190 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
181a0 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20  is called, then 
181b0 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76  it might not hav
181c0 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79  e an opportunity
181d0 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72  .** to be interr
181e0 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20  upted and might 
181f0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70  continue to comp
18200 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41  letion..**.** ^A
18210 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
18220 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70  that is interrup
18230 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ted will return 
18240 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
18250 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69  T]..** ^If the i
18260 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
18270 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
18280 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
18290 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
182a0 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
182b0 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
182c0 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
182d0 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
182e0 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
182f0 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
18300 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ally..**.** ^The
18310 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
18320 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e  pt(D) call is in
18330 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c   effect until al
18340 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  l currently runn
18350 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
18360 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61  ments on [databa
18370 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
18380 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79   complete.  ^Any
18390 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65   new SQL stateme
183a0 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
183b0 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
183c0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
183d0 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62  upt() call and b
183e0 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75  efore the .** ru
183f0 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73  nning statements
18400 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
18410 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73  e interrupted as
18420 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65   if they had bee
18430 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69  n.** running pri
18440 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  or to the sqlite
18450 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
18460 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74  ll.  ^New SQL st
18470 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
18480 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
18490 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73  er the running s
184a0 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72  tatement count r
184b0 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a  eaches zero are.
184c0 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20  ** not effected 
184d0 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  by the sqlite3_i
184e0 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e  nterrupt()..** ^
184f0 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
18500 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74  3_interrupt(D) t
18510 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20  hat occurs when 
18520 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e  there are no run
18530 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
18540 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f  ements is a no-o
18550 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66  p and has no eff
18560 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
18570 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
18580 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
18590 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
185a0 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74  rrupt() call ret
185b0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  urns..**.** If t
185c0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
185d0 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68  ection closes wh
185e0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74  ile [sqlite3_int
185f0 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20  errupt()].** is 
18600 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64  running then bad
18610 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b   things will lik
18620 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76  ely happen..*/.v
18630 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
18640 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
18650 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
18660 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
18670 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
18680 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a  Is Complete.**.*
18690 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
186a0 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69   are useful duri
186b0 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20  ng command-line 
186c0 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69  input to determi
186d0 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72  ne if the.** cur
186e0 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74  rently entered t
186f0 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72  ext seems to for
18700 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  m a complete SQL
18710 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a   statement or.**
18720 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69   if additional i
18730 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62  nput is needed b
18740 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68  efore sending th
18750 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53  e text into.** S
18760 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e  QLite for parsin
18770 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  g.  ^These routi
18780 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20  nes return 1 if 
18790 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
187a0 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62  .** appears to b
187b0 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  e a complete SQL
187c0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20   statement.  ^A 
187d0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64  statement is jud
187e0 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  ged to be.** com
187f0 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73  plete if it ends
18800 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f   with a semicolo
18810 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e  n token and is n
18820 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61  ot a prefix of a
18830 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20  .** well-formed 
18840 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73  CREATE TRIGGER s
18850 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69  tatement.  ^Semi
18860 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
18870 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
18880 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
18890 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
188a0 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
188b0 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
188c0 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
188d0 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
188e0 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
188f0 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
18900 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
18910 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
18920 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
18930 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
18940 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65  or.  ^Whitespace
18950 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73  .** and comments
18960 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65   that follow the
18970 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e   final semicolon
18980 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a   are ignored..**
18990 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
189a0 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20  nes return 0 if 
189b0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
189c0 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49   incomplete.  ^I
189d0 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  f a.** memory al
189e0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20  location fails, 
189f0 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  then SQLITE_NOME
18a00 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  M is returned..*
18a10 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
18a20 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
18a30 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
18a40 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
18a50 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
18a60 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
18a70 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
18a80 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20  ^(If SQLite has 
18a90 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c  not been initial
18aa0 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ized using [sqli
18ab0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
18ac0 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69  ] prior .** to i
18ad0 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
18ae0 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65  complete16() the
18af0 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  n sqlite3_initia
18b00 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
18b10 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  d.** automatical
18b20 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ly by sqlite3_co
18b30 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20  mplete16().  If 
18b40 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74  that initializat
18b50 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68  ion fails,.** th
18b60 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
18b70 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
18b80 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69  _complete16() wi
18b90 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a  ll be non-zero.*
18ba0 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  * regardless of 
18bb0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
18bc0 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20  he input SQL is 
18bd0 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a  complete.)^.**.*
18be0 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
18bf0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
18c00 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
18c10 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
18c20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
18c30 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
18c40 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
18c50 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65  ete16()] must be
18c60 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
18c70 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
18c80 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
18c90 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74  te order..*/.int
18ca0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
18cb0 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
18cc0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
18cd0 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74  complete16(const
18ce0 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a   void *sql);../*
18cf0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
18d00 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63  gister A Callbac
18d10 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49  k To Handle SQLI
18d20 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a  TE_BUSY Errors.*
18d30 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
18d40 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44  3_busy_handler(D
18d50 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 65  ,X,P) routine se
18d60 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  ts a callback fu
18d70 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74  nction X.** that
18d80 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
18d90 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  d with argument 
18da0 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e  P whenever.** an
18db0 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
18dc0 20 74 6f 20 61 63 63 65 73 73 20 61 20 64 61 74   to access a dat
18dd0 61 62 61 73 65 20 74 61 62 6c 65 20 61 73 73 6f  abase table asso
18de0 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b  ciated with.** [
18df0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18e00 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74  ion] D when anot
18e10 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72  her thread.** or
18e20 20 70 72 6f 63 65 73 73 20 68 61 73 20 74 68 65   process has the
18e30 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a   table locked..*
18e40 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75  * The sqlite3_bu
18e50 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e 74  sy_handler() int
18e60 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
18e70 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b  o implement.** [
18e80 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
18e90 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 41  eout()] and [PRA
18ea0 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
18eb0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
18ec0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
18ed0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51  s NULL, then [SQ
18ee0 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73  LITE_BUSY].** is
18ef0 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
18f00 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
18f10 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
18f20 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  .  ^If the busy 
18f30 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
18f40 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
18f50 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74  e callback might
18f60 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
18f70 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a   two arguments..
18f80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
18f90 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
18fa0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
18fb0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
18fc0 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
18fd0 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
18fe0 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
18ff0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
19000 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63  ler().  ^The sec
19010 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
19020 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
19030 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
19040 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
19050 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
19060 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
19070 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f   been invoked fo
19080 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69  r the same locki
19090 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
190a0 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62  he.** busy callb
190b0 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74  ack returns 0, t
190c0 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61  hen no additiona
190d0 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d  l attempts are m
190e0 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73  ade to.** access
190f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
19100 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  d [SQLITE_BUSY] 
19110 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74  is returned.** t
19120 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
19130 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61  n..** ^If the ca
19140 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
19150 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
19160 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a  other attempt.**
19170 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65   is made to acce
19180 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
19190 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65  and the cycle re
191a0 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  peats..**.** The
191b0 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62   presence of a b
191c0 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73  usy handler does
191d0 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74   not guarantee t
191e0 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69  hat it will be i
191f0 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74  nvoked.** when t
19200 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e  here is lock con
19210 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c  tention. ^If SQL
19220 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ite determines t
19230 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hat invoking the
19240 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72   busy.** handler
19250 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   could result in
19260 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20   a deadlock, it 
19270 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e  will go ahead an
19280 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
19290 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65  _BUSY].** to the
192a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73   application ins
192b0 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67  tead of invoking
192c0 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61   the .** busy ha
192d0 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64  ndler..** Consid
192e0 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68  er a scenario wh
192f0 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20  ere one process 
19300 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61  is holding a rea
19310 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69  d lock that.** i
19320 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70  t is trying to p
19330 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65  romote to a rese
19340 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a  rved lock and.**
19350 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73   a second proces
19360 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
19370 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61  eserved lock tha
19380 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a  t it is trying.*
19390 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  * to promote to 
193a0 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63  an exclusive loc
193b0 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72  k.  The first pr
193c0 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f  ocess cannot pro
193d0 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20  ceed.** because 
193e0 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
193f0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
19400 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
19410 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f  ss cannot.** pro
19420 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20  ceed because it 
19430 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
19440 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74  e first.  If bot
19450 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69  h processes.** i
19460 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68  nvoke the busy h
19470 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72  andlers, neither
19480 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70   will make any p
19490 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66  rogress.  Theref
194a0 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72  ore,.** SQLite r
194b0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42  eturns [SQLITE_B
194c0 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72  USY] for the fir
194d0 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69  st process, hopi
194e0 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20  ng that this.** 
194f0 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20  will induce the 
19500 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f  first process to
19510 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61   release its rea
19520 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77  d lock and allow
19530 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70  .** the second p
19540 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65  rocess to procee
19550 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  d..**.** ^The de
19560 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62  fault busy callb
19570 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ack is NULL..**.
19580 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
19590 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
195a0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66  busy handler def
195b0 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a  ined for each.**
195c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
195d0 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67  ction].  Setting
195e0 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64   a new busy hand
195f0 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a  ler clears any.*
19600 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74  * previously set
19610 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f   handler.)^  ^No
19620 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20  te that calling 
19630 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
19640 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65  meout()].** or e
19650 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d  valuating [PRAGM
19660 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e  A busy_timeout=N
19670 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68  ] will change th
19680 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65  e.** busy handle
19690 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72  r and thus clear
196a0 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20   any previously 
196b0 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72  set busy handler
196c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79  ..**.** The busy
196d0 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
196e0 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63   not take any ac
196f0 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69  tions which modi
19700 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  fy the.** databa
19710 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
19720 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
19730 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e  usy handler.  In
19740 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a   other words,.**
19750 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
19760 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61  r is not reentra
19770 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63  nt.  Any such ac
19780 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20  tions.** result 
19790 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
197a0 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20  avior..** .** A 
197b0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73  busy handler mus
197c0 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
197d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
197e0 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61  ion.** or [prepa
197f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
19800 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
19810 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f  busy handler..*/
19820 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
19830 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  y_handler(sqlite
19840 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  3*, int(*)(void*
19850 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  ,int), void*);..
19860 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
19870 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f  Set A Busy Timeo
19880 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  ut.**.** ^This r
19890 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73  outine sets a [s
198a0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
198b0 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c  ler | busy handl
198c0 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a  er] that sleeps.
198d0 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69  ** for a specifi
198e0 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d  ed amount of tim
198f0 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69  e when a table i
19900 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20  s locked.  ^The 
19910 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20  handler.** will 
19920 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74  sleep multiple t
19930 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65  imes until at le
19940 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
19950 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
19960 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75  g.** have accumu
19970 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61  lated.  ^After a
19980 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
19990 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
199a0 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61  eping,.** the ha
199b0 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20  ndler returns 0 
199c0 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71  which causes [sq
199d0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f  lite3_step()] to
199e0 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
199f0 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20  TE_BUSY]..**.** 
19a00 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f  ^Calling this ro
19a10 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72  utine with an ar
19a20 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e  gument less than
19a30 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
19a40 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61  o.** turns off a
19a50 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  ll busy handlers
19a60 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
19a70 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
19a80 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
19a90 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  r for a particul
19aa0 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
19ab0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61  connection] at a
19ac0 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e  ny given moment.
19ad0 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73    If another bus
19ae0 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73  y handler.** was
19af0 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67   defined  (using
19b00 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
19b10 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72  andler()]) prior
19b20 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74   to calling.** t
19b30 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61  his routine, tha
19b40 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  t other busy han
19b50 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e  dler is cleared.
19b60 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
19b70 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79  o:  [PRAGMA busy
19b80 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e 74  _timeout].*/.int
19b90 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69   sqlite3_busy_ti
19ba0 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20  meout(sqlite3*, 
19bb0 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  int ms);../*.** 
19bc0 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e  CAPI3REF: Conven
19bd0 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46  ience Routines F
19be0 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69  or Running Queri
19bf0 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  es.**.** This is
19c00 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66   a legacy interf
19c10 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65 73  ace that is pres
19c20 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61  erved for backwa
19c30 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
19c40 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69  y..** Use of thi
19c50 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  s interface is n
19c60 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  ot recommended..
19c70 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e  **.** Definition
19c80 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61  : A <b>result ta
19c90 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72  ble</b> is memor
19ca0 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  y data structure
19cb0 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a   created by the.
19cc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ** [sqlite3_get_
19cd0 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61  table()] interfa
19ce0 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61  ce.  A result ta
19cf0 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a  ble records the.
19d00 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72  ** complete quer
19d10 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f  y results from o
19d20 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69  ne or more queri
19d30 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  es..**.** The ta
19d40 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79  ble conceptually
19d50 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66   has a number of
19d60 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e   rows and column
19d70 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65  s.  But.** these
19d80 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74   numbers are not
19d90 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73   part of the res
19da0 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66  ult table itself
19db0 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62  .  These.** numb
19dc0 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64  ers are obtained
19dd0 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65   separately.  Le
19de0 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65  t N be the numbe
19df0 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64  r of rows.** and
19e00 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   M be the number
19e10 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a   of columns..**.
19e20 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
19e30 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  e is an array of
19e40 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72   pointers to zer
19e50 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
19e60 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54  -8 strings..** T
19e70 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d  here are (N+1)*M
19e80 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65   elements in the
19e90 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72   array.  The fir
19ea0 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f  st M pointers po
19eb0 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74  int.** to zero-t
19ec0 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
19ed0 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20  s that  contain 
19ee0 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  the names of the
19ef0 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65   columns..** The
19f00 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69   remaining entri
19f10 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20  es all point to 
19f20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20  query results.  
19f30 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75  NULL values resu
19f40 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f  lt.** in NULL po
19f50 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68  inters.  All oth
19f60 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e  er values are in
19f70 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72   their UTF-8 zer
19f80 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
19f90 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74  string represent
19fa0 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65  ation as returne
19fb0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
19fc0 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a  lumn_text()]..**
19fd0 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
19fe0 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74  le might consist
19ff0 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   of one or more 
1a000 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1a010 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  ns..** It is not
1a020 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20   safe to pass a 
1a030 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72  result table dir
1a040 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65  ectly to [sqlite
1a050 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20  3_free()]..** A 
1a060 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f  result table sho
1a070 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  uld be deallocat
1a080 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
1a090 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e  3_free_table()].
1a0a0 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65  .**.** ^(As an e
1a0b0 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65  xample of the re
1a0c0 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61  sult table forma
1a0d0 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65  t, suppose a que
1a0e0 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  ry result.** is 
1a0f0 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1a100 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1a110 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61  re>.**        Na
1a120 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a  me        | Age.
1a130 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d  **        ------
1a140 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1a150 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63  -.**        Alic
1a160 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20  e       | 43.** 
1a170 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20         Bob      
1a180 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20     | 28.**      
1a190 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20    Cindy       | 
1a1a0 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  21.** </pre></bl
1a1b0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1a1c0 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f  There are two co
1a1d0 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20  lumn (M==2) and 
1a1e0 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33  three rows (N==3
1a1f0 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20  ).  Thus the.** 
1a200 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73  result table has
1a210 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70   8 entries.  Sup
1a220 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20  pose the result 
1a230 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a  table is stored.
1a240 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e  ** in an array n
1a250 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20  ames azResult.  
1a260 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f  Then azResult ho
1a270 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74  lds this content
1a280 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1a290 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
1a2a0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1a2b0 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a  ;0] = "Name";.**
1a2c0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1a2d0 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b  &#91;1] = "Age";
1a2e0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1a2f0 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c  ult&#91;2] = "Al
1a300 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ice";.**        
1a310 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20  azResult&#91;3] 
1a320 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20  = "43";.**      
1a330 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34    azResult&#91;4
1a340 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20  ] = "Bob";.**   
1a350 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1a360 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20  1;5] = "28";.** 
1a370 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1a380 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22  #91;6] = "Cindy"
1a390 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1a3a0 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32  sult&#91;7] = "2
1a3b0 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  1";.** </pre></b
1a3c0 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
1a3d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1a3e0 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63  get_table() func
1a3f0 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f  tion evaluates o
1a400 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65  ne or more.** se
1a410 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
1a420 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  d SQL statements
1a430 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   in the zero-ter
1a440 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a  minated UTF-8.**
1a450 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32   string of its 2
1a460 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
1a470 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c   returns a resul
1a480 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a  t table to the.*
1a490 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20  * pointer given 
1a4a0 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d  in its 3rd param
1a4b0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65  eter..**.** Afte
1a4c0 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
1a4d0 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  n has finished w
1a4e0 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66  ith the result f
1a4f0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  rom sqlite3_get_
1a500 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d  table(),.** it m
1a510 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65 73  ust pass the res
1a520 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65  ult table pointe
1a530 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  r to sqlite3_fre
1a540 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64  e_table() in ord
1a550 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65  er to.** release
1a560 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74   the memory that
1a570 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20   was malloced.  
1a580 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77  Because of the w
1a590 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ay the.** [sqlit
1a5a0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70  e3_malloc()] hap
1a5b0 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69  pens within sqli
1a5c0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
1a5d0 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20   the calling.** 
1a5e0 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  function must no
1a5f0 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73  t try to call [s
1a600 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64  qlite3_free()] d
1a610 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a  irectly.  Only.*
1a620 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  * [sqlite3_free_
1a630 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65  table()] is able
1a640 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20   to release the 
1a650 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20  memory properly 
1a660 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a  and safely..**.*
1a670 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
1a680 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66  t_table() interf
1a690 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74  ace is implement
1a6a0 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20  ed as a wrapper 
1a6b0 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  around.** [sqlit
1a6c0 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65  e3_exec()].  The
1a6d0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1a6e0 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  le() routine doe
1a6f0 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73  s not have acces
1a700 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65  s.** to any inte
1a710 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74  rnal data struct
1a720 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ures of SQLite. 
1a730 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68   It uses only th
1a740 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65  e public.** inte
1a750 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65  rface defined he
1a760 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71  re.  As a conseq
1a770 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68  uence, errors th
1a780 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a  at occur in the.
1a790 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72  ** wrapper layer
1a7a0 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
1a7b0 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65  internal [sqlite
1a7c0 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61  3_exec()] call a
1a7d0 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63  re not.** reflec
1a7e0 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e  ted in subsequen
1a7f0 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
1a800 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f  te3_errcode()] o
1a810 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  r.** [sqlite3_er
1a820 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  rmsg()]..*/.int 
1a830 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1a840 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
1a850 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e  ,          /* An
1a860 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
1a870 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1a880 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c  zSql,     /* SQL
1a890 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
1a8a0 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61   */.  char ***pa
1a8b0 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52  zResult,    /* R
1a8c0 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75  esults of the qu
1a8d0 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ery */.  int *pn
1a8e0 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f  Row,           /
1a8f0 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
1a900 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20  lt rows written 
1a910 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  here */.  int *p
1a920 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20  nColumn,        
1a930 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
1a940 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74  ult columns writ
1a950 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68  ten here */.  ch
1a960 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20  ar **pzErrmsg   
1a970 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
1a980 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
1a990 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .);.void sqlite3
1a9a0 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72  _free_table(char
1a9b0 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a   **result);../*.
1a9c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72  ** CAPI3REF: For
1a9d0 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72  matted String Pr
1a9e0 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  inting Functions
1a9f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1aa00 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61  tines are work-a
1aa10 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72  likes of the "pr
1aa20 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f  intf()" family o
1aa30 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66  f functions.** f
1aa40 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
1aa50 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a   C library..**.*
1aa60 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
1aa70 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c  printf() and sql
1aa80 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20  ite3_vmprintf() 
1aa90 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74  routines write t
1aaa0 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20  heir.** results 
1aab0 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
1aac0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
1aad0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a  e3_malloc()]..**
1aae0 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   The strings ret
1aaf0 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74  urned by these t
1ab00 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75  wo routines shou
1ab10 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65  ld be.** release
1ab20 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72  d by [sqlite3_fr
1ab30 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f  ee()].  ^Both ro
1ab40 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a  utines return a.
1ab50 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
1ab60 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  if [sqlite3_mall
1ab70 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20  oc()] is unable 
1ab80 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75  to allocate enou
1ab90 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20  gh.** memory to 
1aba0 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69  hold the resulti
1abb0 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ng string..**.**
1abc0 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73   ^(The sqlite3_s
1abd0 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
1abe0 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
1abf0 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f  "snprintf()" fro
1ac00 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72  m.** the standar
1ac10 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68  d C library.  Th
1ac20 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74  e result is writ
1ac30 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ten into the.** 
1ac40 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20  buffer supplied 
1ac50 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
1ac60 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69  rameter whose si
1ac70 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a  ze is given by.*
1ac80 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  * the first para
1ac90 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74  meter. Note that
1aca0 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68   the order of th
1acb0 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70  e.** first two p
1acc0 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76  arameters is rev
1acd0 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69  ersed from snpri
1ace0 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69  ntf().)^  This i
1acf0 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63  s an.** historic
1ad00 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74  al accident that
1ad10 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64   cannot be fixed
1ad20 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
1ad30 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  g.** backwards c
1ad40 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e  ompatibility.  ^
1ad50 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20  (Note also that 
1ad60 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1ad70 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
1ad80 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62  pointer to its b
1ad90 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66  uffer instead of
1ada0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
1adb0 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74  * characters act
1adc0 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e  ually written in
1add0 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e  to the buffer.)^
1ade0 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a    We admit that.
1adf0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
1ae00 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74   characters writ
1ae10 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d  ten would be a m
1ae20 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72  ore useful retur
1ae30 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77  n.** value but w
1ae40 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20  e cannot change 
1ae50 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
1ae60 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
1ae70 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20  printf().** now 
1ae80 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
1ae90 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
1aea0 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61  **.** ^As long a
1aeb0 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a  s the buffer siz
1aec0 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  e is greater tha
1aed0 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f  n zero, sqlite3_
1aee0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75  snprintf().** gu
1aef0 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
1af00 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61  e buffer is alwa
1af10 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
1af20 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a  ed.  ^The first.
1af30 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22  ** parameter "n"
1af40 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69   is the total si
1af50 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
1af60 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63  , including spac
1af70 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72  e for.** the zer
1af80 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53  o terminator.  S
1af90 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74  o the longest st
1afa0 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65  ring that can be
1afb0 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77   completely.** w
1afc0 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e  ritten will be n
1afd0 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -1 characters..*
1afe0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1aff0 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  3_vsnprintf() ro
1b000 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 72  utine is a varar
1b010 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71  gs version of sq
1b020 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1b030 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
1b040 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65  utines all imple
1b050 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69  ment some additi
1b060 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a  onal formatting.
1b070 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20  ** options that 
1b080 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63  are useful for c
1b090 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20  onstructing SQL 
1b0a0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41  statements..** A
1b0b0 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20  ll of the usual 
1b0c0 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74  printf() formatt
1b0d0 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c  ing options appl
1b0e0 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c  y.  In addition,
1b0f0 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65   there.** is are
1b100 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64   "%q", "%Q", and
1b110 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a   "%z" options..*
1b120 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70  *.** ^(The %q op
1b130 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1b140 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75  %s in that it su
1b150 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d  bstitutes a nul-
1b160 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
1b170 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72  ring from the ar
1b180 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75  gument list.  Bu
1b190 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65  t %q also double
1b1a0 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61  s every '\'' cha
1b1b0 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73  racter..** %q is
1b1c0 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73   designed for us
1b1d0 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e  e inside a strin
1b1e0 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79  g literal.)^  By
1b1f0 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27   doubling each '
1b200 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  \''.** character
1b210 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74   it escapes that
1b220 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61   character and a
1b230 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69  llows it to be i
1b240 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20  nserted into.** 
1b250 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  the string..**.*
1b260 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61  * For example, a
1b270 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67  ssume the string
1b280 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20   variable zText 
1b290 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73  contains text as
1b2a0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1b2b0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1b2c0 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78  >.**  char *zTex
1b2d0 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70  t = "It's a happ
1b2e0 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72  y day!";.** </pr
1b2f0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1b300 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73  **.** One can us
1b310 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61  e this text in a
1b320 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
1b330 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1b340 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1b350 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
1b360 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
1b370 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
1b380 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27  O table VALUES('
1b390 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  %q')", zText);.*
1b3a0 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
1b3b0 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
1b3c0 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
1b3d0 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
1b3e0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1b3f0 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  e>.**.** Because
1b400 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73   the %q format s
1b410 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74  tring is used, t
1b420 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  he '\'' characte
1b430 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73  r in zText.** is
1b440 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65   escaped and the
1b450 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69   SQL generated i
1b460 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
1b470 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1b480 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
1b490 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
1b4a0 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70  UES('It''s a hap
1b4b0 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70  py day!').** </p
1b4c0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1b4d0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63  .**.** This is c
1b4e0 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20  orrect.  Had we 
1b4f0 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20  used %s instead 
1b500 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72  of %q, the gener
1b510 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c  ated SQL.** woul
1b520 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69  d have looked li
1b530 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
1b540 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1b550 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
1b560 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
1b570 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
1b580 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  !');.** </pre></
1b590 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1b5a0 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78  * This second ex
1b5b0 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20  ample is an SQL 
1b5c0 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41  syntax error.  A
1b5d0 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65  s a general rule
1b5e0 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61   you should.** a
1b5f0 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73  lways use %q ins
1b600 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20  tead of %s when 
1b610 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69  inserting text i
1b620 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74  nto a string lit
1b630 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  eral..**.** ^(Th
1b640 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %Q option work
1b650 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74  s like %q except
1b660 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69   it also adds si
1b670 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75  ngle quotes arou
1b680 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64  nd.** the outsid
1b690 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73  e of the total s
1b6a0 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e  tring.  Addition
1b6b0 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72  ally, if the par
1b6c0 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a  ameter in the.**
1b6d0 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69   argument list i
1b6e0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1b6f0 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73  , %Q substitutes
1b700 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22   the text "NULL"
1b710 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e   (without.** sin
1b720 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20  gle quotes).)^  
1b730 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  So, for example,
1b740 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a   one could say:.
1b750 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1b760 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
1b770 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
1b780 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
1b790 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
1b7a0 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b  ES(%Q)", zText);
1b7b0 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
1b7c0 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
1b7d0 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
1b7e0 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
1b7f0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1b800 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ote>.**.** The c
1b810 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72  ode above will r
1b820 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20  ender a correct 
1b830 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
1b840 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72   the zSQL.** var
1b850 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68  iable even if th
1b860 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65  e zText variable
1b870 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1b880 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  er..**.** ^(The 
1b890 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%z" formatting 
1b8a0 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
1b8b0 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20  e "%s" but with 
1b8c0 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20  the.** addition 
1b8d0 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73  that after the s
1b8e0 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72  tring has been r
1b8f0 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69  ead and copied i
1b900 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  nto.** the resul
1b910 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  t, [sqlite3_free
1b920 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e  ()] is called on
1b930 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
1b940 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71  g.)^.*/.char *sq
1b950 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f  lite3_mprintf(co
1b960 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a  nst char*,...);.
1b970 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d  char *sqlite3_vm
1b980 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
1b990 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68  r*, va_list);.ch
1b9a0 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72  ar *sqlite3_snpr
1b9b0 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
1b9c0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29  onst char*, ...)
1b9d0 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
1b9e0 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  vsnprintf(int,ch
1b9f0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1ba00 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a   va_list);../*.*
1ba10 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
1ba20 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75  ry Allocation Su
1ba30 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68  bsystem.**.** Th
1ba40 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73  e SQLite core us
1ba50 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72  es these three r
1ba60 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20  outines for all 
1ba70 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e  of its own.** in
1ba80 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c  ternal memory al
1ba90 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20  location needs. 
1baa0 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72  "Core" in the pr
1bab0 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a  evious sentence.
1bac0 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ** does not incl
1bad0 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  ude operating-sy
1bae0 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46  stem specific VF
1baf0 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
1bb00 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77  .  The.** Window
1bb10 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76  s VFS uses nativ
1bb20 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  e malloc() and f
1bb30 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f  ree() for some o
1bb40 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
1bb50 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61   ^The sqlite3_ma
1bb60 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72  lloc() routine r
1bb70 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1bb80 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f   to a block.** o
1bb90 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73  f memory at leas
1bba0 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e  t N bytes in len
1bbb0 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20  gth, where N is 
1bbc0 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
1bbd0 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  * ^If sqlite3_ma
1bbe0 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65  lloc() is unable
1bbf0 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69   to obtain suffi
1bc00 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65  cient free.** me
1bc10 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73  mory, it returns
1bc20 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1bc30 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65    ^If the parame
1bc40 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69  ter N to.** sqli
1bc50 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
1bc60 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65  zero or negative
1bc70 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61   then sqlite3_ma
1bc80 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a  lloc() returns.*
1bc90 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
1bca0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
1bcb0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1bcc0 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70  with a pointer p
1bcd0 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
1bce0 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
1bcf0 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
1bd00 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
1bd10 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d  eleases that mem
1bd20 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69  ory so.** that i
1bd30 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65  t might be reuse
1bd40 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
1bd50 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20  _free() routine 
1bd60 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66  is.** a no-op if
1bd70 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
1bd80 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
1bd90 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20   Passing a NULL 
1bda0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71  pointer.** to sq
1bdb0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
1bdc0 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72  harmless.  After
1bdd0 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65   being freed, me
1bde0 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  mory.** should n
1bdf0 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e  either be read n
1be00 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65  or written.  Eve
1be10 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f  n reading previo
1be20 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65  usly freed.** me
1be30 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c  mory might resul
1be40 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74  t in a segmentat
1be50 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68  ion fault or oth
1be60 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e  er severe error.
1be70 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75  .** Memory corru
1be80 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74  ption, a segment
1be90 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20  ation fault, or 
1bea0 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
1beb0 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75  or.** might resu
1bec0 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72  lt if sqlite3_fr
1bed0 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77  ee() is called w
1bee0 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  ith a non-NULL p
1bef0 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77  ointer that.** w
1bf00 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20  as not obtained 
1bf10 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
1bf20 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
1bf30 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a  _realloc()..**.*
1bf40 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
1bf50 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66  realloc() interf
1bf60 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
1bf70 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f  resize a.** prio
1bf80 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  r memory allocat
1bf90 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61  ion to be at lea
1bfa0 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72  st N bytes, wher
1bfb0 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65  e N is the.** se
1bfc0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
1bfd0 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   The memory allo
1bfe0 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73  cation to be res
1bff0 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73  ized is the firs
1c000 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29  t.** parameter.)
1c010 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72 73 74  ^ ^ If the first
1c020 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1c030 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a  lite3_realloc().
1c040 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
1c050 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65  nter then its be
1c060 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69  havior is identi
1c070 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  cal to calling.*
1c080 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1c090 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 74  (N) where N is t
1c0a0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1c0b0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1c0c0 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66  ealloc()..** ^If
1c0d0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1c0e0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1c0f0 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  _realloc() is ze
1c100 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76  ro or.** negativ
1c110 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  e then the behav
1c120 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74  ior is exactly t
1c130 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69  he same as calli
1c140 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72  ng.** sqlite3_fr
1c150 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69 73  ee(P) where P is
1c160 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
1c170 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1c180 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73  realloc()..** ^s
1c190 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1c1a0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1c1b0 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61  er to a memory a
1c1c0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
1c1d0 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1c1e0 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c   in size or NULL
1c1f0 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d   if sufficient m
1c200 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c  emory is unavail
1c210 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69  able..** ^If M i
1c220 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
1c230 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1c240 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d  on, then min(N,M
1c250 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68  ) bytes.** of th
1c260 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1c270 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e  on are copied in
1c280 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
1c290 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72   of buffer retur
1c2a0 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
1c2b0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  3_realloc() and 
1c2c0 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1c2d0 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a  tion is freed..*
1c2e0 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65  * ^If sqlite3_re
1c2f0 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20  alloc() returns 
1c300 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70  NULL, then the p
1c310 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  rior allocation.
1c320 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e  ** is not freed.
1c330 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f  .**.** ^The memo
1c340 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ry returned by s
1c350 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1c360 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  and sqlite3_real
1c370 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61  loc().** is alwa
1c380 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74  ys aligned to at
1c390 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65   least an 8 byte
1c3a0 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f   boundary, or to
1c3b0 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75   a.** 4 byte bou
1c3c0 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51  ndary if the [SQ
1c3d0 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47  LITE_4_BYTE_ALIG
1c3e0 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70  NED_MALLOC] comp
1c3f0 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
1c400 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
1c410 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73  * In SQLite vers
1c420 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e  ion 3.5.0 and 3.
1c430 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73  5.1, it was poss
1c440 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a  ible to define.*
1c450 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49  * the SQLITE_OMI
1c460 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54  T_MEMORY_ALLOCAT
1c470 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20  ION which would 
1c480 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d  cause the built-
1c490 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  in.** implementa
1c4a0 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f  tion of these ro
1c4b0 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69  utines to be omi
1c4c0 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61  tted.  That capa
1c4d0 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20  bility.** is no 
1c4e0 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e  longer provided.
1c4f0 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20    Only built-in 
1c500 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
1c510 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a  s can be used..*
1c520 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51  *.** Prior to SQ
1c530 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
1c540 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73  .10, the Windows
1c550 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
1c560 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68  yer called.** th
1c570 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
1c580 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72  ) and free() dir
1c590 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65  ectly when conve
1c5a0 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d  rting.** filenam
1c5b0 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55  es between the U
1c5c0 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73  TF-8 encoding us
1c5d0 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
1c5e0 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c  and whatever fil
1c5f0 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69  ename encoding i
1c600 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61  s used by the pa
1c610 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73  rticular Windows
1c620 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e  .** installation
1c630 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  .  Memory alloca
1c640 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65  tion errors were
1c650 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a   detected, but.*
1c660 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f  * they were repo
1c670 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
1c680 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
1c690 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
1c6a0 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
1c6b0 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
1c6c0 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
1c6d0 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b  r arguments to [
1c6e0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1c6f0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
1c700 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20  lloc()].** must 
1c710 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f  be either NULL o
1c720 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20  r else pointers 
1c730 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
1c740 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74  prior.** invocat
1c750 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
1c760 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
1c770 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1c780 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f   that have.** no
1c790 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61  t yet been relea
1c7a0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  sed..**.** The a
1c7b0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
1c7c0 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74  not read or writ
1c7d0 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a  e any part of.**
1c7e0 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f   a block of memo
1c7f0 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20  ry after it has 
1c800 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73  been released us
1c810 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1c820 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  free()] or [sqli
1c830 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a  te3_realloc()]..
1c840 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
1c850 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f  _malloc(int);.vo
1c860 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
1c870 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  loc(void*, int);
1c880 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
1c890 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ee(void*);../*.*
1c8a0 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
1c8b0 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61  ry Allocator Sta
1c8c0 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51  tistics.**.** SQ
1c8d0 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68  Lite provides th
1c8e0 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63  ese two interfac
1c8f0 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67  es for reporting
1c900 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a   on the status.*
1c910 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
1c920 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71  3_malloc()], [sq
1c930 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61  lite3_free()], a
1c940 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
1c950 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e  loc()].** routin
1c960 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74  es, which form t
1c970 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  he built-in memo
1c980 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
1c990 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  bsystem..**.** ^
1c9a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
1c9b0 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74  ory_used()] rout
1c9c0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
1c9d0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a  number of bytes.
1c9e0 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72  ** of memory cur
1c9f0 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69  rently outstandi
1ca00 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74  ng (malloced but
1ca10 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20   not freed)..** 
1ca20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
1ca30 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1ca40 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
1ca50 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
1ca60 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74   value of [sqlit
1ca70 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1ca80 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68  ] since the high
1ca90 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77  -water mark.** w
1caa0 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20  as last reset.  
1cab0 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
1cac0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
1cad0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1cae0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
1caf0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1cb00 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20  ()] include any 
1cb10 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65  overhead.** adde
1cb20 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69  d by SQLite in i
1cb30 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ts implementatio
1cb40 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
1cb50 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20  lloc()],.** but 
1cb60 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64  not overhead add
1cb70 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e  ed by the any un
1cb80 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20  derlying system 
1cb90 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69  library.** routi
1cba0 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65  nes that [sqlite
1cbb0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20  3_malloc()] may 
1cbc0 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  call..**.** ^The
1cbd0 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74   memory high-wat
1cbe0 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74  er mark is reset
1cbf0 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   to the current 
1cc00 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c  value of.** [sql
1cc10 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1cc20 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ()] if and only 
1cc30 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
1cc40 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
1cc50 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1cc60 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54  ()] is true.  ^T
1cc70 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1cc80 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
1cc90 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1cca0 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67  r(1)] is the hig
1ccb0 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
1ccc0 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73  prior to the res
1ccd0 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  et..*/.sqlite3_i
1cce0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
1ccf0 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a  ory_used(void);.
1cd00 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
1cd10 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1cd20 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74  hwater(int reset
1cd30 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Flag);../*.** CA
1cd40 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52  PI3REF: Pseudo-R
1cd50 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e  andom Number Gen
1cd60 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c  erator.**.** SQL
1cd70 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68  ite contains a h
1cd80 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75  igh-quality pseu
1cd90 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72  do-random number
1cda0 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47   generator (PRNG
1cdb0 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c  ) used to.** sel
1cdc0 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49  ect random [ROWI
1cdd0 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e  D | ROWIDs] when
1cde0 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72   inserting new r
1cdf0 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61  ecords into a ta
1ce00 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65  ble that.** alre
1ce10 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72  ady uses the lar
1ce20 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52  gest possible [R
1ce30 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47  OWID].  The PRNG
1ce40 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f   is also used fo
1ce50 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69  r.** the build-i
1ce60 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72  n random() and r
1ce70 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20  andomblob() SQL 
1ce80 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73  functions.  This
1ce90 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
1cea0 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  s.** application
1ceb0 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
1cec0 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74  same PRNG for ot
1ced0 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a  her purposes..**
1cee0 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74  .** ^A call to t
1cef0 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
1cf00 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61  es N bytes of ra
1cf10 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75  ndomness into bu
1cf20 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 49 66 20 4e  ffer P..** ^If N
1cf30 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e   is less than on
1cf40 65 2c 20 74 68 65 6e 20 50 20 63 61 6e 20 62 65  e, then P can be
1cf50 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1cf60 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20  .**.** ^If this 
1cf70 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20  routine has not 
1cf80 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20  been previously 
1cf90 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65  called or if the
1cfa0 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c   previous.** cal
1cfb0 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61  l had N less tha
1cfc0 6e 20 6f 6e 65 2c 20 74 68 65 6e 20 74 68 65 20  n one, then the 
1cfd0 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20 75  PRNG is seeded u
1cfe0 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 0a  sing randomness.
1cff0 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ** obtained from
1d000 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   the xRandomness
1d010 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64   method of the d
1d020 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
1d030 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  vfs] object..** 
1d040 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f 75 73  ^If the previous
1d050 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f   call to this ro
1d060 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f  utine had an N o
1d070 66 20 31 20 6f 72 20 6d 6f 72 65 20 74 68 65 6e  f 1 or more then
1d080 0a 2a 2a 20 74 68 65 20 70 73 65 75 64 6f 2d 72  .** the pseudo-r
1d090 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e  andomness is gen
1d0a0 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e  erated.** intern
1d0b0 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74  ally and without
1d0c0 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65   recourse to the
1d0d0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78   [sqlite3_vfs] x
1d0e0 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65  Randomness.** me
1d0f0 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  thod..*/.void sq
1d100 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73  lite3_randomness
1d110 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29  (int N, void *P)
1d120 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1d130 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20  F: Compile-Time 
1d140 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61  Authorization Ca
1d150 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
1d160 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69  his routine regi
1d170 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69  sters an authori
1d180 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74  zer callback wit
1d190 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  h a particular.*
1d1a0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1d1b0 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65  ection], supplie
1d1c0 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
1d1d0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
1d1e0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1d1f0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
1d200 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  as SQL statement
1d210 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70  s are being comp
1d220 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  iled.** by [sqli
1d230 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
1d240 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b  r its variants [
1d250 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1d260 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
1d270 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
1d280 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
1d290 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e  pare16_v2()].  ^
1d2a0 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f  At various.** po
1d2b0 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20  ints during the 
1d2c0 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63  compilation proc
1d2d0 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73  ess, as logic is
1d2e0 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a   being created.*
1d2f0 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  * to perform var
1d300 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68  ious actions, th
1d310 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1d320 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1d330 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68   to.** see if th
1d340 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20  ose actions are 
1d350 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61  allowed.  ^The a
1d360 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1d370 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ck should.** ret
1d380 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
1d390 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74  to allow the act
1d3a0 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e  ion, [SQLITE_IGN
1d3b0 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77  ORE] to disallow
1d3c0 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
1d3d0 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f   action but allo
1d3e0 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  w the SQL statem
1d3f0 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20  ent to continue 
1d400 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  to be.** compile
1d410 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  d, or [SQLITE_DE
1d420 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65  NY] to cause the
1d430 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74   entire SQL stat
1d440 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72  ement to be.** r
1d450 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20  ejected with an 
1d460 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20  error.  ^If the 
1d470 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1d480 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ack returns.** a
1d490 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
1d4a0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  han [SQLITE_IGNO
1d4b0 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  RE], [SQLITE_OK]
1d4c0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
1d4d0 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b  Y].** then the [
1d4e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1d4f0 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
1d500 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
1d510 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61  iggered.** the a
1d520 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
1d530 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
1d540 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
1d550 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
1d560 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
1d570 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61  TE_OK], that mea
1d580 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  ns the operation
1d590 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73  .** requested is
1d5a0 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20   ok.  ^When the 
1d5b0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1d5c0 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20   [SQLITE_DENY], 
1d5d0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1d5e0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1d5f0 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
1d600 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20   that triggered 
1d610 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
1d620 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
1d630 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
1d640 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61  e explaining tha
1d650 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64  t.** access is d
1d660 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54  enied. .**.** ^T
1d670 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1d680 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
1d690 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1d6a0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74   a copy of the t
1d6b0 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
1d6c0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
1d6d0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1d6e0 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68  ) interface. ^Th
1d6f0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1d700 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  er.** to the cal
1d710 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
1d720 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59  ger [SQLITE_COPY
1d730 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20   | action code] 
1d740 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
1d750 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  * the particular
1d760 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
1d770 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74  thorized. ^The t
1d780 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78  hird through six
1d790 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  th parameters.**
1d7a0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
1d7b0 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   are zero-termin
1d7c0 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
1d7d0 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69  t contain additi
1d7e0 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20  onal.** details 
1d7f0 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e  about the action
1d800 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
1d810 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
1d820 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
1d830 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a  [SQLITE_READ].**
1d840 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
1d850 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
1d860 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
1d870 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
1d880 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65  statement] state
1d890 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63  ment is construc
1d8a0 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74  ted to substitut
1d8b0 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75  e.** a NULL valu
1d8c0 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68  e in place of th
1d8d0 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  e table column t
1d8e0 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a  hat would have.*
1d8f0 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b  * been read if [
1d900 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62  SQLITE_OK] had b
1d910 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54  een returned.  T
1d920 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  he [SQLITE_IGNOR
1d930 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e  E].** return can
1d940 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79   be used to deny
1d950 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73   an untrusted us
1d960 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64  er access to ind
1d970 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d  ividual.** colum
1d980 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a  ns of a table..*
1d990 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
1d9a0 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
1d9b0 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65  _DELETE] and the
1d9c0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1d9d0 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e  s.** [SQLITE_IGN
1d9e0 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44  ORE] then the [D
1d9f0 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e  ELETE] operation
1da00 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68   proceeds but th
1da10 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f  e.** [truncate o
1da20 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20  ptimization] is 
1da30 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c  disabled and all
1da40 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
1da50 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a  d individually..
1da60 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69  **.** An authori
1da70 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e  zer is used when
1da80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1da90 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a  e | preparing].*
1daa0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
1dab0 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74   from an untrust
1dac0 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e  ed source, to en
1dad0 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51  sure that the SQ
1dae0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
1daf0 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63  do not try to ac
1db00 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61  cess data they a
1db10 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74  re not allowed t
1db20 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74  o see, or that t
1db30 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72  hey do not.** tr
1db40 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c  y to execute mal
1db50 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74  icious statement
1db60 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68  s that damage th
1db70 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72  e database.  For
1db80 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  .** example, an 
1db90 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20  application may 
1dba0 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20  allow a user to 
1dbb0 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a  enter arbitrary.
1dbc0 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66  ** SQL queries f
1dbd0 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79  or evaluation by
1dbe0 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75   a database.  Bu
1dbf0 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1dc00 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  n does.** not wa
1dc10 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62  nt the user to b
1dc20 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61  e able to make a
1dc30 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73  rbitrary changes
1dc40 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
1dc50 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69  ase.  An authori
1dc60 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62  zer could then b
1dc70 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77  e put in place w
1dc80 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72  hile the.** user
1dc90 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20  -entered SQL is 
1dca0 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  being [sqlite3_p
1dcb0 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65  repare | prepare
1dcc0 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c  d] that.** disal
1dcd0 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20  lows everything 
1dce0 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20  except [SELECT] 
1dcf0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
1dd00 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
1dd10 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63  hat need to proc
1dd20 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74  ess SQL from unt
1dd30 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a  rusted sources.*
1dd40 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e  * might also con
1dd50 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72  sider lowering r
1dd60 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75  esource limits u
1dd70 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
1dd80 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69  mit()].** and li
1dd90 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  miting database 
1dda0 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b  size using the [
1ddb0 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
1ddc0 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61  [PRAGMA].** in a
1ddd0 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67  ddition to using
1dde0 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a   an authorizer..
1ddf0 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73  **.** ^(Only a s
1de00 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72  ingle authorizer
1de10 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65   can be in place
1de20 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63   on a database c
1de30 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20  onnection.** at 
1de40 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61  a time.  Each ca
1de50 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
1de60 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65  t_authorizer ove
1de70 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72  rrides the.** pr
1de80 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20  evious call.)^  
1de90 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74  ^Disable the aut
1dea0 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61  horizer by insta
1deb0 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c  lling a NULL cal
1dec0 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75  lback..** The au
1ded0 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61  thorizer is disa
1dee0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
1def0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
1df00 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
1df10 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
1df20 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
1df30 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
1df40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1df50 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1df60 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1df70 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  back..** Note th
1df80 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
1df90 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
1dfa0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
1dfb0 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
1dfc0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1dfd0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
1dfe0 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
1dff0 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
1e000 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57  agraph..**.** ^W
1e010 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
1e020 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73  pare_v2()] is us
1e030 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20  ed to prepare a 
1e040 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a  statement, the.*
1e050 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68  * statement migh
1e060 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64  t be re-prepared
1e070 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33   during [sqlite3
1e080 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20  _step()] due to 
1e090 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61  a .** schema cha
1e0a0 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  nge.  Hence, the
1e0b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
1e0c0 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20  uld ensure that 
1e0d0 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61  the.** correct a
1e0e0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1e0f0 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c  ck remains in pl
1e100 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b  ace during the [
1e110 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
1e120 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61  .**.** ^Note tha
1e130 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  t the authorizer
1e140 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1e150 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67  oked only during
1e160 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1e170 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
1e180 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72  ariants.  Author
1e190 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a  ization is not.*
1e1a0 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69  * performed duri
1e1b0 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61  ng statement eva
1e1c0 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69  luation in [sqli
1e1d0 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c  te3_step()], unl
1e1e0 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64  ess.** as stated
1e1f0 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
1e200 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69   paragraph, sqli
1e210 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b  te3_step() invok
1e220 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  es.** sqlite3_pr
1e230 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65  epare_v2() to re
1e240 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
1e250 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65  ent after a sche
1e260 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e  ma change..*/.in
1e270 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  t sqlite3_set_au
1e280 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69  thorizer(.  sqli
1e290 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41  te3*,.  int (*xA
1e2a0 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  uth)(void*,int,c
1e2b0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
1e2c0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
1e2d0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  r*,const char*),
1e2e0 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61  .  void *pUserDa
1e2f0 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ta.);../*.** CAP
1e300 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
1e310 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a  r Return Codes.*
1e320 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
1e330 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1e340 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   | authorizer ca
1e350 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d  llback function]
1e360 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20   must.** return 
1e370 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f  either [SQLITE_O
1e380 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  K] or one of the
1e390 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73  se two constants
1e3a0 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20   in order.** to 
1e3b0 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68  signal SQLite wh
1e3c0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
1e3d0 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69   action is permi
1e3e0 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a  tted.  See the.*
1e3f0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  * [sqlite3_set_a
1e400 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
1e410 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61  orizer documenta
1e420 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69  tion] for additi
1e430 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
1e440 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ion..**.** Note 
1e450 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f  that SQLITE_IGNO
1e460 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  RE is also used 
1e470 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72  as a [conflict r
1e480 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a  esolution mode].
1e490 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ** returned from
1e4a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74   the [sqlite3_vt
1e4b0 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29  ab_on_conflict()
1e4c0 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a  ] interface..*/.
1e4d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1e4e0 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f  ENY   1   /* Abo
1e4f0 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
1e500 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72  ment with an err
1e510 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
1e520 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20  LITE_IGNORE 2   
1e530 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61  /* Don't allow a
1e540 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74  ccess, but don't
1e550 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72   generate an err
1e560 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  or */../*.** CAP
1e570 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
1e580 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a  r Action Codes.*
1e590 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
1e5a0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1e5b0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
1e5c0 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
1e5d0 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  ck function.** t
1e5e0 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  hat is invoked t
1e5f0 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74  o authorize cert
1e600 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ain SQL statemen
1e610 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  t actions.  The.
1e620 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
1e630 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
1e640 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
1e650 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63  r code that spec
1e660 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63  ifies.** what ac
1e670 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75  tion is being au
1e680 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65  thorized.  These
1e690 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72   are the integer
1e6a0 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68   action codes th
1e6b0 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  at.** the author
1e6c0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61  izer callback ma
1e6d0 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a  y be passed..**.
1e6e0 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20  ** These action 
1e6f0 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e  code values sign
1e700 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  ify what kind of
1e710 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f   operation is to
1e720 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65   be.** authorize
1e730 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20  d.  The 3rd and 
1e740 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  4th parameters t
1e750 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  o the authorizat
1e760 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ion.** callback 
1e770 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65  function will be
1e780 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
1e790 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
1e7a0 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a   which of these.
1e7b0 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64  ** codes is used
1e7c0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
1e7d0 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65  arameter.  ^(The
1e7e0 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
1e7f0 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  o the.** authori
1e800 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1e810 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
1e820 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22  database ("main"
1e830 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63  , "temp",.** etc
1e840 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
1e850 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61  .)^  ^The 6th pa
1e860 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
1e870 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1e880 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ck.** is the nam
1e890 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d  e of the inner-m
1e8a0 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
1e8b0 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
1e8c0 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74  onsible for.** t
1e8d0 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
1e8e0 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
1e8f0 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
1e900 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
1e910 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53  m.** top-level S
1e920 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a  QL code..*/./***
1e930 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e940 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e950 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a  ******** 3rd ***
1e960 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a  ********* 4th **
1e970 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69  *********/.#defi
1e980 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1e990 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
1e9a0 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  1   /* Index Nam
1e9b0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1e9c0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1e9d0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1e9e0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
1e9f0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1ea00 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1ea10 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1ea20 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1ea30 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20  EMP_INDEX     3 
1ea40 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1ea50 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1ea60 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1ea70 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1ea80 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20  MP_TABLE     4  
1ea90 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1eaa0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1eab0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1eac0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1ead0 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20  P_TRIGGER   5   
1eae0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1eaf0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1eb00 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1eb10 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1eb20 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f  _VIEW      6   /
1eb30 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1eb40 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1eb50 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1eb60 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47  ITE_CREATE_TRIGG
1eb70 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  ER        7   /*
1eb80 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1eb90 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1eba0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ebb0 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20  TE_CREATE_VIEW  
1ebc0 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20           8   /* 
1ebd0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1ebe0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1ebf0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ec00 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  E_DELETE        
1ec10 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54          9   /* T
1ec20 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1ec30 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1ec40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ec50 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20  _DROP_INDEX     
1ec60 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e        10   /* In
1ec70 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1ec80 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1ec90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1eca0 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20  DROP_TABLE      
1ecb0 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62       11   /* Tab
1ecc0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1ecd0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1ece0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1ecf0 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ROP_TEMP_INDEX  
1ed00 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65      12   /* Inde
1ed10 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1ed20 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1ed30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1ed40 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  OP_TEMP_TABLE   
1ed50 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65     13   /* Table
1ed60 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1ed70 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1ed80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1ed90 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  P_TEMP_TRIGGER  
1eda0 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65    14   /* Trigge
1edb0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1edc0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1edd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1ede0 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
1edf0 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   15   /* View Na
1ee00 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1ee10 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1ee20 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1ee30 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20  TRIGGER         
1ee40 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  16   /* Trigger 
1ee50 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1ee60 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1ee70 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
1ee80 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31  IEW            1
1ee90 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  7   /* View Name
1eea0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1eeb0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1eec0 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20  e SQLITE_INSERT 
1eed0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
1eee0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1eef0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1ef00 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1ef10 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20   SQLITE_PRAGMA  
1ef20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20               19 
1ef30 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65    /* Pragma Name
1ef40 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20       1st arg or 
1ef50 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  NULL */.#define 
1ef60 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20  SQLITE_READ     
1ef70 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20              20  
1ef80 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1ef90 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
1efa0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1efb0 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20  QLITE_SELECT    
1efc0 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20             21   
1efd0 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
1efe0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1eff0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f000 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e  LITE_TRANSACTION
1f010 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f            22   /
1f020 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
1f030 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1f040 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f050 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20  ITE_UPDATE      
1f060 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a           23   /*
1f070 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f080 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
1f090 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f0a0 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20  TE_ATTACH       
1f0b0 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20          24   /* 
1f0c0 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20  Filename        
1f0d0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f0e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f0f0 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20  E_DETACH        
1f100 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44         25   /* D
1f110 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e  atabase Name   N
1f120 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1f130 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f140 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20  _ALTER_TABLE    
1f150 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61        26   /* Da
1f160 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61  tabase Name   Ta
1f170 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1f180 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f190 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  REINDEX         
1f1a0 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64       27   /* Ind
1f1b0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  ex Name      NUL
1f1c0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1f1d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
1f1e0 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20  NALYZE          
1f1f0 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c      28   /* Tabl
1f200 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1f210 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1f220 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1f230 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20  EATE_VTABLE     
1f240 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65     29   /* Table
1f250 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
1f260 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
1f270 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1f280 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  P_VTABLE        
1f290 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    30   /* Table 
1f2a0 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
1f2b0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1f2c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43  fine SQLITE_FUNC
1f2d0 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20  TION            
1f2e0 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   31   /* NULL   
1f2f0 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f           Functio
1f300 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66  n Name   */.#def
1f310 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50  ine SQLITE_SAVEP
1f320 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  OINT            
1f330 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  32   /* Operatio
1f340 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e  n       Savepoin
1f350 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69  t Name  */.#defi
1f360 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20  ne SQLITE_COPY  
1f370 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1f380 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72  0   /* No longer
1f390 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65   used */.#define
1f3a0 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56   SQLITE_RECURSIV
1f3b0 45 20 20 20 20 20 20 20 20 20 20 20 20 33 33 20  E            33 
1f3c0 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
1f3d0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1f3e0 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43       */../*.** C
1f3f0 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67  API3REF: Tracing
1f400 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46   And Profiling F
1f410 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
1f420 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
1f430 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20  gister callback 
1f440 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63  functions that c
1f450 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a  an be used for.*
1f460 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72  * tracing and pr
1f470 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63  ofiling the exec
1f480 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61  ution of SQL sta
1f490 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
1f4a0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
1f4b0 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
1f4c0 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63   by sqlite3_trac
1f4d0 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  e() is invoked a
1f4e0 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d  t.** various tim
1f4f0 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73  es when an SQL s
1f500 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e  tatement is bein
1f510 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65  g run by [sqlite
1f520 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54  3_step()]..** ^T
1f530 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
1f540 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  () callback is i
1f550 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54  nvoked with a UT
1f560 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
1f570 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74   the.** SQL stat
1f580 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68  ement text as th
1f590 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  e statement firs
1f5a0 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69  t begins executi
1f5b0 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f  ng..** ^(Additio
1f5c0 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63  nal sqlite3_trac
1f5d0 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69  e() callbacks mi
1f5e0 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20  ght occur.** as 
1f5f0 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73  each triggered s
1f600 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74  ubprogram is ent
1f610 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62  ered.  The callb
1f620 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72  acks for trigger
1f630 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55  s.** contain a U
1f640 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  TF-8 SQL comment
1f650 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73   that identifies
1f660 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a   the trigger.)^.
1f670 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
1f680 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d  E_TRACE_SIZE_LIM
1f690 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  IT] compile-time
1f6a0 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
1f6b0 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20  sed to limit.** 
1f6c0 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62  the length of [b
1f6d0 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20  ound parameter] 
1f6e0 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65  expansion in the
1f6f0 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74   output of sqlit
1f700 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a  e3_trace()..**.*
1f710 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
1f720 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
1f730 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70  red by sqlite3_p
1f740 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f  rofile() is invo
1f750 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53  ked.** as each S
1f760 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e  QL statement fin
1f770 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f  ishes.  ^The pro
1f780 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f  file callback co
1f790 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72  ntains.** the or
1f7a0 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
1f7b0 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74   text and an est
1f7c0 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c  imate of wall-cl
1f7d0 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68  ock time.** of h
1f7e0 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61  ow long that sta
1f7f0 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72  tement took to r
1f800 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c  un.  ^The profil
1f810 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69  e callback.** ti
1f820 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f  me is in units o
1f830 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68  f nanoseconds, h
1f840 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65  owever the curre
1f850 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
1f860 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70  n.** is only cap
1f870 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63  able of millisec
1f880 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73  ond resolution s
1f890 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20  o the six least 
1f8a0 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64  significant.** d
1f8b0 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d  igits in the tim
1f8c0 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73  e are meaningles
1f8d0 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  s.  Future versi
1f8e0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ons of SQLite.**
1f8f0 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67   might provide g
1f900 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f  reater resolutio
1f910 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65  n on the profile
1f920 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65  r callback.  The
1f930 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66  .** sqlite3_prof
1f940 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ile() function i
1f950 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70  s considered exp
1f960 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73  erimental and is
1f970 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63  .** subject to c
1f980 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20  hange in future 
1f990 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
1f9a0 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  te..*/.void *sql
1f9b0 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74  ite3_trace(sqlit
1f9c0 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63  e3*, void(*xTrac
1f9d0 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
1f9e0 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53  har*), void*);.S
1f9f0 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
1fa00 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  AL void *sqlite3
1fa10 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33  _profile(sqlite3
1fa20 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f  *,.   void(*xPro
1fa30 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  file)(void*,cons
1fa40 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f  t char*,sqlite3_
1fa50 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b  uint64), void*);
1fa60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1fa70 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73  : Query Progress
1fa80 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
1fa90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72   ^The sqlite3_pr
1faa0 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44  ogress_handler(D
1fab0 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63  ,N,X,P) interfac
1fac0 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  e causes the cal
1fad0 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
1fae0 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  n X to be invoke
1faf0 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64  d periodically d
1fb00 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69  uring long runni
1fb10 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ng calls to.** [
1fb20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
1fb30 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1fb40 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67  ] and [sqlite3_g
1fb50 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a  et_table()] for.
1fb60 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1fb70 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78  ection D.  An ex
1fb80 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68  ample use for th
1fb90 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  is.** interface 
1fba0 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49  is to keep a GUI
1fbb0 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20   updated during 
1fbc0 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a  a large query..*
1fbd0 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65  *.** ^The parame
1fbe0 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20  ter P is passed 
1fbf0 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f  through as the o
1fc00 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
1fc10 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63   the .** callbac
1fc20 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e  k function X.  ^
1fc30 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  The parameter N 
1fc40 69 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61  is the approxima
1fc50 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a  te number of .**
1fc60 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e   [virtual machin
1fc70 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20  e instructions] 
1fc80 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74  that are evaluat
1fc90 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65  ed between succe
1fca0 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  ssive.** invocat
1fcb0 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c  ions of the call
1fcc0 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69  back X.  ^If N i
1fcd0 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20  s less than one 
1fce0 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73  then the progres
1fcf0 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20  s.** handler is 
1fd00 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  disabled..**.** 
1fd10 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70  ^Only a single p
1fd20 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
1fd30 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61  may be defined a
1fd40 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a  t one time per.*
1fd50 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1fd60 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67  ection]; setting
1fd70 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20   a new progress 
1fd80 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20  handler cancels 
1fd90 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20  the.** old one. 
1fda0 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65   ^Setting parame
1fdb0 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69  ter X to NULL di
1fdc0 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72  sables the progr
1fdd0 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
1fde0 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61  ^The progress ha
1fdf0 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69  ndler is also di
1fe00 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e  sabled by settin
1fe10 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c  g N to a value l
1fe20 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a  ess.** than 1..*
1fe30 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f  *.** ^If the pro
1fe40 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72  gress callback r
1fe50 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
1fe60 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69   the operation i
1fe70 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64  s.** interrupted
1fe80 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20  .  This feature 
1fe90 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69  can be used to i
1fea0 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43  mplement a.** "C
1feb0 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e  ancel" button on
1fec0 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20   a GUI progress 
1fed0 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a  dialog box..**.*
1fee0 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68  * The progress h
1fef0 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
1ff00 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
1ff10 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
1ff20 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
1ff30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1ff40 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1ff50 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1ff60 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  er..** Note that
1ff70 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1ff80 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
1ff90 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
1ffa0 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
1ffb0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1ffc0 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
1ffd0 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
1ffe0 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
1fff0 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64  raph..**.*/.void
20000 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
20010 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  s_handler(sqlite
20020 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28  3*, int, int(*)(
20030 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
20040 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
20050 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44   Opening A New D
20060 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
20070 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  on.**.** ^These 
20080 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e  routines open an
20090 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
200a0 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 69   file as specifi
200b0 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69  ed by the .** fi
200c0 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e  lename argument.
200d0 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61   ^The filename a
200e0 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72  rgument is inter
200f0 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20  preted as UTF-8 
20100 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
20110 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
20120 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20  3_open_v2() and 
20130 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  as UTF-16 in the
20140 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20   native byte.** 
20150 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65  order for sqlite
20160 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20  3_open16(). ^(A 
20170 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
20180 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20  tion] handle is 
20190 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72  usually.** retur
201a0 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76  ned in *ppDb, ev
201b0 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f  en if an error o
201c0 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79  ccurs.  The only
201d0 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68   exception is th
201e0 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20  at.** if SQLite 
201f0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
20200 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20  ocate memory to 
20210 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65  hold the [sqlite
20220 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20  3] object,.** a 
20230 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69  NULL will be wri
20240 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20  tten into *ppDb 
20250 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69  instead of a poi
20260 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
20270 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e  ite3].** object.
20280 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61  )^ ^(If the data
20290 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28  base is opened (
202a0 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20  and/or created) 
202b0 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68  successfully, th
202c0 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  en.** [SQLITE_OK
202d0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  ] is returned.  
202e0 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  Otherwise an [er
202f0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
20300 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a  urned.)^ ^The.**
20310 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
20320 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
20330 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74  errmsg16()] rout
20340 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64  ines can be used
20350 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e   to obtain.** an
20360 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67   English languag
20370 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66  e description of
20380 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f   the error follo
20390 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f  wing a failure o
203a0 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20  f any.** of the 
203b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72  sqlite3_open() r
203c0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
203d0 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
203e0 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74  ding for the dat
203f0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54  abase will be UT
20400 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65  F-8 if.** sqlite
20410 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
20420 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
20430 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55   called and.** U
20440 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
20450 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
20460 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  f sqlite3_open16
20470 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  () is used..**.*
20480 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * Whether or not
20490 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
204a0 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e   when it is open
204b0 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a  ed, resources.**
204c0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
204d0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
204e0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
204f0 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65  e should be rele
20500 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69  ased by.** passi
20510 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
20520 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20  3_close()] when 
20530 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  it is no longer 
20540 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
20550 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  The sqlite3_open
20560 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
20570 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
20580 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63  e3_open().** exc
20590 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65  ept that it acce
205a0 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e  pts two addition
205b0 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f  al parameters fo
205c0 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e  r additional con
205d0 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65  trol.** over the
205e0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
205f0 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65  nnection.  ^(The
20600 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
20610 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   to.** sqlite3_o
20620 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b  pen_v2() can tak
20630 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20  e one of.** the 
20640 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20  following three 
20650 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c  values, optional
20660 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
20670 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
20680 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20  _OPEN_NOMUTEX], 
20690 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
206a0 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  LMUTEX], [SQLITE
206b0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
206c0 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  E],.** [SQLITE_O
206d0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
206e0 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54  ], and/or [SQLIT
206f0 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
20700 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  s:)^.**.** <dl>.
20710 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
20720 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c  _OPEN_READONLY]<
20730 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
20740 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
20750 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20  ed in read-only 
20760 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61  mode.  If the da
20770 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a  tabase does not.
20780 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ** already exist
20790 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  , an error is re
207a0 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
207b0 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
207c0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
207d0 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
207e0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
207f0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
20800 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
20810 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65   possible, or re
20820 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66  ading.** only if
20830 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69   the file is wri
20840 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20  te protected by 
20850 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
20860 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72  stem.  In either
20870 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74  .** case the dat
20880 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61  abase must alrea
20890 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77  dy exist, otherw
208a0 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20  ise an error is 
208b0 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
208c0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
208d0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
208e0 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
208f0 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e  PEN_CREATE]</dt>
20900 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
20910 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
20920 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
20930 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63  riting, and is c
20940 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20  reated if.** it 
20950 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79  does not already
20960 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20   exist. This is 
20970 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61  the behavior tha
20980 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  t is always used
20990 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
209a0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
209b0 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64  e3_open16().</dd
209c0 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a  >)^.** </dl>.**.
209d0 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
209e0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
209f0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
20a00 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
20a10 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73  * combinations s
20a20 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f  hown above optio
20a30 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
20a40 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51  ith other.** [SQ
20a50 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
20a60 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e  LY | SQLITE_OPEN
20a70 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e  _* bits].** then
20a80 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
20a90 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
20aa0 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54  * ^If the [SQLIT
20ab0 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20  E_OPEN_NOMUTEX] 
20ac0 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65  flag is set, the
20ad0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
20ae0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65  onnection.** ope
20af0 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d  ns in the multi-
20b00 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
20b10 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20  g mode] as long 
20b20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68  as the single-th
20b30 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73  read.** mode has
20b40 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74   not been set at
20b50 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
20b60 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49   start-time.  ^I
20b70 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  f the.** [SQLITE
20b80 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
20b90 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65   flag is set the
20ba0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
20bb0 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a  onnection opens.
20bc0 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c  ** in the serial
20bd0 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
20be0 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e  mode] unless sin
20bf0 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a  gle-thread was.*
20c00 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c  * previously sel
20c10 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  ected at compile
20c20 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
20c30 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ime..** ^The [SQ
20c40 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
20c50 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
20c60 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
20c70 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65  connection to be
20c80 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20  .** eligible to 
20c90 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68  use [shared cach
20ca0 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c  e mode], regardl
20cb0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
20cc0 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20  r not shared.** 
20cd0 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64  cache is enabled
20ce0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
20cf0 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
20d00 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a  che()].  ^The.**
20d10 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
20d20 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67  IVATECACHE] flag
20d30 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
20d40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
20d50 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63  to not.** partic
20d60 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64  ipate in [shared
20d70 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65   cache mode] eve
20d80 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c  n if it is enabl
20d90 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
20da0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
20db0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
20dc0 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65  v2() is the name
20dd0 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
20de0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
20df0 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65  that defines the
20e00 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
20e10 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
20e20 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61  .** the new data
20e30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
20e40 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66  should use.  ^If
20e50 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
20e60 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55  meter is.** a NU
20e70 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
20e80 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
20e90 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
20ea0 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
20eb0 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
20ec0 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
20ed0 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
20ee0 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d  temporary in-mem
20ef0 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ory database.** 
20f00 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74  is created for t
20f10 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  he connection.  
20f20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20  ^This in-memory 
20f30 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61  database will va
20f40 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65  nish when.** the
20f50 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
20f60 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20  tion is closed. 
20f70 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
20f80 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
20f90 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20  .** make use of 
20fa0 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69  additional speci
20fb0 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61  al filenames tha
20fc0 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65  t begin with the
20fd0 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a   ":" character..
20fe0 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** It is recomme
20ff0 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61  nded that when a
21000 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
21010 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73  me actually does
21020 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61   begin with.** a
21030 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79   ":" character y
21040 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78  ou should prefix
21050 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69   the filename wi
21060 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75  th a pathname su
21070 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f  ch as.** "./" to
21080 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79   avoid ambiguity
21090 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
210a0 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65  filename is an e
210b0 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65  mpty string, the
210c0 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
210d0 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73  porary.** on-dis
210e0 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  k database will 
210f0 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68  be created.  ^Th
21100 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62  is private datab
21110 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61  ase will be.** a
21120 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
21130 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  eted as soon as 
21140 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
21150 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
21160 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  d..**.** [[URI f
21170 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69  ilenames in sqli
21180 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33  te3_open()]] <h3
21190 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f  >URI Filenames</
211a0 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55  h3>.**.** ^If [U
211b0 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74  RI filename] int
211c0 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
211d0 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20  nabled, and the 
211e0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
211f0 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68  t.** begins with
21200 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74   "file:", then t
21210 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69  he filename is i
21220 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
21230 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c  URI. ^URI.** fil
21240 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
21250 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20  tion is enabled 
21260 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
21270 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
21280 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66  .** set in the f
21290 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
212a0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
212b0 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61  2(), or if it ha
212c0 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65  s.** been enable
212d0 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67  d globally using
212e0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
212f0 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20  FIG_URI] option 
21300 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  with the.** [sql
21310 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d  ite3_config()] m
21320 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20  ethod or by the 
21330 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d  [SQLITE_USE_URI]
21340 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
21350 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53  tion..** As of S
21360 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
21370 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d  7.7, URI filenam
21380 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  e interpretation
21390 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a   is turned off.*
213a0 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75  * by default, bu
213b0 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  t future release
213c0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
213d0 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c  t enable URI fil
213e0 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72  ename.** interpr
213f0 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75  etation by defau
21400 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66  lt.  See "[URI f
21410 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61  ilenames]" for a
21420 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
21430 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
21440 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72  URI filenames ar
21450 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69  e parsed accordi
21460 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20  ng to RFC 3986. 
21470 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74  ^If the URI cont
21480 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f  ains an.** autho
21490 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75  rity, then it mu
214a0 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20  st be either an 
214b0 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
214c0 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22  the string .** "
214d0 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20  localhost". ^If 
214e0 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73  the authority is
214f0 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74   not an empty st
21500 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f  ring or "localho
21510 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f  st", an .** erro
21520 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f  r is returned to
21530 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68   the caller. ^Th
21540 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f  e fragment compo
21550 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69  nent of a URI, i
21560 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69  f .** present, i
21570 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
21580 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
21590 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74  e path component
215a0 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74   of the URI as t
215b0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
215c0 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63  isk file.** whic
215d0 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  h contains the d
215e0 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65  atabase. ^If the
215f0 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74   path begins wit
21600 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65  h a '/' characte
21610 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  r, .** then it i
21620 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
21630 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
21640 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  h. ^If the path 
21650 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a  does not begin .
21660 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d  ** with a '/' (m
21670 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20  eaning that the 
21680 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f  authority sectio
21690 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  n is omitted fro
216a0 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68  m the URI).** th
216b0 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69  en the path is i
216c0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
216d0 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a  relative path. .
216e0 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c 20  ** ^On windows, 
216f0 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e  the first compon
21700 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75  ent of an absolu
21710 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61  te path .** is a
21720 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63 61   drive specifica
21730 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29  tion (e.g. "C:")
21740 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55  ..**.** [[core U
21750 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  RI query paramet
21760 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65  ers]].** The que
21770 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  ry component of 
21780 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69  a URI may contai
21790 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61  n parameters tha
217a0 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  t are interprete
217b0 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53  d.** either by S
217c0 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72  QLite itself, or
217d0 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73   by a [VFS | cus
217e0 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  tom VFS implemen
217f0 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69  tation]..** SQLi
21800 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  te interprets th
21810 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
21820 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  e query paramete
21830 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  rs:.**.** <ul>.*
21840 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c  *   <li> <b>vfs<
21850 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20  /b>: ^The "vfs" 
21860 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
21870 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79   used to specify
21880 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20   the name of.** 
21890 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74      a VFS object
218a0 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 74   that provides t
218b0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
218c0 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
218d0 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20  at should.**    
218e0 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 65   be used to acce
218f0 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
21900 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49  file on disk. ^I
21910 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  f this option is
21920 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61   set to.**     a
21930 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74  n empty string t
21940 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f  he default VFS o
21950 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e  bject is used. ^
21960 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e  Specifying an un
21970 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53  known.**     VFS
21980 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49   is an error. ^I
21990 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  f sqlite3_open_v
219a0 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20  2() is used and 
219b0 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69  the vfs option i
219c0 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74  s.**     present
219d0 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 73  , then the VFS s
219e0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
219f0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65  option takes pre
21a00 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20  cedence over.** 
21a10 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 61      the value pa
21a20 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72  ssed as the four
21a30 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
21a40 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
21a50 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20  )..**.**   <li> 
21a60 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54  <b>mode</b>: ^(T
21a70 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65  he mode paramete
21a80 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20  r may be set to 
21a90 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77  either "ro", "rw
21aa0 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c  ",.**     "rwc",
21ab0 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74   or "memory". At
21ac0 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20  tempting to set 
21ad0 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20  it to any other 
21ae0 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20  value is.**     
21af0 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20  an error)^. .** 
21b00 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20      ^If "ro" is 
21b10 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20  specified, then 
21b20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
21b30 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d  opened for read-
21b40 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63  only .**     acc
21b50 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20  ess, just as if 
21b60 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
21b70 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20  _READONLY] flag 
21b80 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20  had been set in 
21b90 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72  the .**     thir
21ba0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
21bb0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
21bc0 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70   ^If the mode op
21bd0 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a  tion is set to .
21be0 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68 65  **     "rw", the
21bf0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
21c00 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
21c10 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74  d-write (but not
21c20 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20   create) .**    
21c30 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20 53   access, as if S
21c40 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
21c50 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51  RITE (but not SQ
21c60 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
21c70 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65  ) had .**     be
21c80 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22  en set. ^Value "
21c90 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c 65  rwc" is equivale
21ca0 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f  nt to setting bo
21cb0 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  th .**     SQLIT
21cc0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
21cd0 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e   and SQLITE_OPEN
21ce0 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68  _CREATE.  ^If th
21cf0 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73  e mode option is
21d00 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22  .**     set to "
21d10 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70  memory" then a p
21d20 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64  ure [in-memory d
21d30 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65  atabase] that ne
21d40 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20  ver reads.**    
21d50 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20   or writes from 
21d60 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49  disk is used. ^I
21d70 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f  t is an error to
21d80 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75 65   specify a value
21d90 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20   for.**     the 
21da0 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 74  mode parameter t
21db0 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 73 74  hat is less rest
21dc0 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 68 61  rictive than tha
21dd0 74 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  t specified by.*
21de0 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 73 20  *     the flags 
21df0 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 74 68  passed in the th
21e00 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
21e10 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
21e20 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e  ()..**.**   <li>
21e30 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e   <b>cache</b>: ^
21e40 54 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65  The cache parame
21e50 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74  ter may be set t
21e60 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 65 64  o either "shared
21e70 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69  " or.**     "pri
21e80 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20  vate". ^Setting 
21e90 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 20 69  it to "shared" i
21ea0 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
21eb0 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20  setting the.**  
21ec0 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53     SQLITE_OPEN_S
21ed0 48 41 52 45 44 43 41 43 48 45 20 62 69 74 20 69  HAREDCACHE bit i
21ee0 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  n the flags argu
21ef0 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a  ment passed to.*
21f00 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70  *     sqlite3_op
21f10 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e  en_v2(). ^Settin
21f20 67 20 74 68 65 20 63 61 63 68 65 20 70 61 72 61  g the cache para
21f30 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 61 74  meter to "privat
21f40 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71  e" is .**     eq
21f50 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
21f60 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  ing the SQLITE_O
21f70 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
21f80 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66   bit..**     ^If
21f90 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
21fa0 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74  () is used and t
21fb0 68 65 20 22 63 61 63 68 65 22 20 70 61 72 61 6d  he "cache" param
21fc0 65 74 65 72 20 69 73 20 70 72 65 73 65 6e 74 20  eter is present 
21fd0 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20  in.**     a URI 
21fe0 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61  filename, its va
21ff0 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e  lue overrides an
22000 79 20 62 65 68 61 76 69 6f 72 20 72 65 71 75 65  y behavior reque
22010 73 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a  sted by setting.
22020 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
22030 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
22040 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  or SQLITE_OPEN_S
22050 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e  HAREDCACHE flag.
22060 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e  .**.**  <li> <b>
22070 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70  psow</b>: ^The p
22080 73 6f 77 20 70 61 72 61 6d 65 74 65 72 20 6d 61  sow parameter ma
22090 79 20 62 65 20 22 74 72 75 65 22 20 28 6f 72 20  y be "true" (or 
220a0 22 6f 6e 22 20 6f 72 20 22 79 65 73 22 20 6f 72  "on" or "yes" or
220b0 0a 2a 2a 20 20 20 20 20 22 31 22 29 20 6f 72 20  .**     "1") or 
220c0 22 66 61 6c 73 65 22 20 28 6f 72 20 22 6f 66 66  "false" (or "off
220d0 22 20 6f 72 20 22 6e 6f 22 20 6f 72 20 22 30 22  " or "no" or "0"
220e0 29 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  ) to indicate th
220f0 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70  at the.**     [p
22100 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 69  owersafe overwri
22110 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65  te] property doe
22120 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70  s or does not ap
22130 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20  ply to the.**   
22140 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20    storage media 
22150 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 61 74  on which the dat
22160 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 69 64  abase file resid
22170 65 73 2e 20 20 5e 54 68 65 20 70 73 6f 77 20 71  es.  ^The psow q
22180 75 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61  uery.**     para
22190 6d 65 74 65 72 20 6f 6e 6c 79 20 77 6f 72 6b 73  meter only works
221a0 20 66 6f 72 20 74 68 65 20 62 75 69 6c 74 2d 69   for the built-i
221b0 6e 20 75 6e 69 78 20 61 6e 64 20 57 69 6e 64 6f  n unix and Windo
221c0 77 73 20 56 46 53 65 73 2e 0a 2a 2a 0a 2a 2a 20  ws VFSes..**.** 
221d0 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c   <li> <b>nolock<
221e0 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b  /b>: ^The nolock
221f0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
22200 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 70 61  boolean query pa
22210 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 77  rameter.**     w
22220 68 69 63 68 20 69 66 20 73 65 74 20 64 69 73 61  hich if set disa
22230 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e  bles file lockin
22240 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f  g in rollback jo
22250 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68  urnal modes.  Th
22260 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 73 65  is.**     is use
22270 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73 69 6e  ful for accessin
22280 67 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20  g a database on 
22290 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74 68 61  a filesystem tha
222a0 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20  t does not.**   
222b0 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e    support lockin
222c0 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 44 61  g.  Caution:  Da
222d0 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f  tabase corruptio
222e0 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  n might result i
222f0 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20  f two.**     or 
22300 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73 20 77  more processes w
22310 72 69 74 65 20 74 6f 20 74 68 65 20 73 61 6d 65  rite to the same
22320 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6e   database and an
22330 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a  y one of those.*
22340 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65 73 20  *     processes 
22350 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a  uses nolock=1..*
22360 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d  *.**  <li> <b>im
22370 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68  mutable</b>: ^Th
22380 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 72 61  e immutable para
22390 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65  meter is a boole
223a0 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20  an query.**     
223b0 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69  parameter that i
223c0 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68  ndicates that th
223d0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
223e0 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20  is stored on.** 
223f0 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65      read-only me
22400 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75  dia.  ^When immu
22410 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20 53 51  table is set, SQ
22420 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
22430 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61 74  t the.**     dat
22440 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f  abase file canno
22450 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20 65 76  t be changed, ev
22460 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73 73 20  en by a process 
22470 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a 20 20  with higher.**  
22480 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20 61 6e     privilege, an
22490 64 20 73 6f 20 74 68 65 20 64 61 74 61 62 61 73  d so the databas
224a0 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65 61 64  e is opened read
224b0 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f  -only and all lo
224c0 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64  cking.**     and
224d0 20 63 68 61 6e 67 65 20 64 65 74 65 63 74 69 6f   change detectio
224e0 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20  n is disabled.  
224f0 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67  Caution: Setting
22500 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a   the immutable.*
22510 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79 20 6f  *     property o
22520 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
22530 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e 20 66  e that does in f
22540 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e 20 72  act change can r
22550 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20  esult.**     in 
22560 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72 79 20  incorrect query 
22570 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b  results and/or [
22580 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 20  SQLITE_CORRUPT] 
22590 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53  errors..**     S
225a0 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45  ee also: [SQLITE
225b0 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45  _IOCAP_IMMUTABLE
225c0 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20  ]..**       .** 
225d0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65  </ul>.**.** ^Spe
225e0 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f  cifying an unkno
225f0 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  wn parameter in 
22600 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  the query compon
22610 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 20  ent of a URI is 
22620 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e  not an.** error.
22630 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
22640 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
22650 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64  t understand add
22660 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a  itional query.**
22670 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65   parameters.  Se
22680 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65  e "[query parame
22690 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69 61  ters with specia
226a0 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c  l meaning to SQL
226b0 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64  ite]" for.** add
226c0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
226d0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  ion..**.** [[URI
226e0 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c   filename exampl
226f0 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c  es]] <h3>URI fil
22700 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f  ename examples</
22710 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65  h3>.**.** <table
22720 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67   border="1" alig
22730 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64  n=center cellpad
22740 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c  ding=5>.** <tr><
22750 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  th> URI filename
22760 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a  s <th> Results.*
22770 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
22780 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a  data.db <td> .**
22790 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74            Open t
227a0 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  he file "data.db
227b0 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  " in the current
227c0 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c   directory..** <
227d0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f  tr><td> file:/ho
227e0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c  me/fred/data.db<
227f0 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  br>.**          
22800 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65  file:///home/fre
22810 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a  d/data.db <br> .
22820 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
22830 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d  ://localhost/hom
22840 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
22850 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  br> <td> .**    
22860 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64        Open the d
22870 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68  atabase file "/h
22880 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
22890 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  "..** <tr><td> f
228a0 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68  ile://darkstar/h
228b0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
228c0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
228d0 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61     An error. "da
228e0 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61  rkstar" is not a
228f0 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68   recognized auth
22900 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  ority..** <tr><t
22910 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73  d style="white-s
22920 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a  pace:nowrap"> .*
22930 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
22940 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25  ///C:/Documents%
22950 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73  20and%20Settings
22960 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61  /fred/Desktop/da
22970 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64  ta.db.**     <td
22980 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20  > Windows only: 
22990 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
229a0 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27  ata.db" on fred'
229b0 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69  s desktop on dri
229c0 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43  ve.**          C
229d0 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  :. Note that the
229e0 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e   %20 escaping in
229f0 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73   this example is
22a00 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a   not strictly .*
22a10 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 73  *          neces
22a20 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 61  sary - space cha
22a30 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 75  racters can be u
22a40 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a  sed literally.**
22a50 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 49            in URI
22a60 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c   filenames..** <
22a70 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
22a80 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63  a.db?mode=ro&cac
22a90 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20  he=private <td> 
22aa0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
22ab0 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  n file "data.db"
22ac0 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
22ad0 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65  directory for re
22ae0 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a  ad-only access..
22af0 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 61  **          Rega
22b00 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
22b10 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d  r or not shared-
22b20 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e  cache mode is en
22b30 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  abled by.**     
22b40 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73       default, us
22b50 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63 68  e a private cach
22b60 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  e..** <tr><td> f
22b70 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  ile:/home/fred/d
22b80 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d  ata.db?vfs=unix-
22b90 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20  dotfile <td>.** 
22ba0 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69           Open fi
22bb0 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
22bc0 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65  ata.db". Use the
22bd0 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e   special VFS "un
22be0 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20  ix-dotfile".**  
22bf0 20 20 20 20 20 20 20 20 74 68 61 74 20 75 73 65          that use
22c00 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70  s dot-files in p
22c10 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20 61 64  lace of posix ad
22c20 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a  visory locking..
22c30 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
22c40 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65  :data.db?mode=re
22c50 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20  adonly <td> .** 
22c60 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f           An erro
22c70 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73  r. "readonly" is
22c80 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74   not a valid opt
22c90 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64  ion for the "mod
22ca0 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  e" parameter..**
22cb0 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20   </table>.**.** 
22cc0 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c  ^URI hexadecimal
22cd0 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
22ce0 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70 70  s (%HH) are supp
22cf0 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68 65  orted within the
22d00 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65   path and.** que
22d10 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66  ry components of
22d20 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64 65   a URI. A hexade
22d30 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
22d40 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f  uence consists o
22d50 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73  f a.** percent s
22d60 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c  ign - "%" - foll
22d70 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79 20  owed by exactly 
22d80 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20  two hexadecimal 
22d90 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69  digits .** speci
22da0 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76  fying an octet v
22db0 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68  alue. ^Before th
22dc0 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79 20  e path or query 
22dd0 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a  components of a.
22de0 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  ** URI filename 
22df0 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c  are interpreted,
22e00 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65   they are encode
22e10 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e  d using UTF-8 an
22e20 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65  d all .** hexade
22e30 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
22e40 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20  uences replaced 
22e50 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65  by a single byte
22e60 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a   containing the.
22e70 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  ** corresponding
22e80 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73 20   octet. If this 
22e90 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65  process generate
22ea0 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46  s an invalid UTF
22eb0 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20  -8 encoding,.** 
22ec0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
22ed0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
22ee0 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
22ef0 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20  ows users:</b>  
22f00 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  The encoding use
22f10 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61  d for the filena
22f20 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f  me argument.** o
22f30 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  f sqlite3_open()
22f40 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
22f50 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55  n_v2() must be U
22f60 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76  TF-8, not whatev
22f70 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69  er.** codepage i
22f80 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  s currently defi
22f90 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20  ned.  Filenames 
22fa0 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72  containing inter
22fb0 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72  national.** char
22fc0 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63  acters must be c
22fd0 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d  onverted to UTF-
22fe0 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69  8 prior to passi
22ff0 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20  ng them into.** 
23000 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
23010 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
23020 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  2()..**.** <b>No
23030 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75  te to Windows Ru
23040 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e  ntime users:</b>
23050 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20    The temporary 
23060 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62  directory must b
23070 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74  e set.** prior t
23080 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65  o calling sqlite
23090 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
230a0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20  te3_open_v2().  
230b0 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f  Otherwise, vario
230c0 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74  us.** features t
230d0 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65 20  hat require the 
230e0 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79  use of temporary
230f0 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e   files may fail.
23100 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
23110 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64   [sqlite3_temp_d
23120 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74  irectory].*/.int
23130 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20   sqlite3_open(. 
23140 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
23150 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
23160 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
23170 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
23180 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
23190 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
231a0 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
231b0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  ;.int sqlite3_op
231c0 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f  en16(.  const vo
231d0 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  id *filename,   
231e0 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
231f0 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f  name (UTF-16) */
23200 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
23210 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
23220 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
23230 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  dle */.);.int sq
23240 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20  lite3_open_v2(. 
23250 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
23260 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
23270 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
23280 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
23290 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20  e3 **ppDb,      
232a0 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
232b0 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  e db handle */. 
232c0 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20   int flags,     
232d0 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67           /* Flag
232e0 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  s */.  const cha
232f0 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f  r *zVfs        /
23300 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f  * Name of VFS mo
23310 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29  dule to use */.)
23320 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
23330 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73  F: Obtain Values
23340 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74   For URI Paramet
23350 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ers.**.** These 
23360 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74  are utility rout
23370 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20  ines, useful to 
23380 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
23390 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a  ons, that check.
233a0 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64  ** to see if a d
233b0 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73  atabase file was
233c0 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74   a URI that cont
233d0 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63  ained a specific
233e0 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d   query .** param
233f0 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20  eter, and if so 
23400 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75  obtains the valu
23410 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 20  e of that query 
23420 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
23430 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61 74   If F is the dat
23440 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70  abase filename p
23450 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e  ointer passed in
23460 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d  to the xOpen() m
23470 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56  ethod of .** a V
23480 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
23490 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73  n when the flags
234a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
234b0 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72  pen() has one or
234c0 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65   .** more of the
234d0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
234e0 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  I] or [SQLITE_OP
234f0 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73  EN_MAIN_DB] bits
23500 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73   set and.** P is
23510 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
23520 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
23530 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
23540 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
23550 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 65  F,P) returns the
23560 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a   value of the P.
23570 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20  ** parameter if 
23580 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e  it exists or a N
23590 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50  ULL pointer if P
235a0 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72   does not appear
235b0 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20   as a .** query 
235c0 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20  parameter on F. 
235d0 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72 79   If P is a query
235e0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a   parameter of F.
235f0 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63  ** has no explic
23600 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73  it value, then s
23610 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
23620 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
23630 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
23640 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  o an empty strin
23650 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  g..**.** The sql
23660 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
23670 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20  (F,P,B) routine 
23680 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 69  assumes that P i
23690 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70  s a boolean.** p
236a0 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
236b0 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72  urns true (1) or
236c0 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72   false (0) accor
236d0 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75  ding to the valu
236e0 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20  e.** of P.  The 
236f0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
23700 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
23710 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ne returns true 
23720 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61  (1) if the.** va
23730 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 72  lue of query par
23740 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20  ameter P is one 
23750 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 22  of "yes", "true"
23760 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79  , or "on" in any
23770 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74  .** case or if t
23780 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20  he value begins 
23790 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  with a non-zero 
237a0 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a  number.  The .**
237b0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
237c0 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
237d0 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c  ines returns fal
237e0 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76 61  se (0) if the va
237f0 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20  lue of.** query 
23800 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f  parameter P is o
23810 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c  ne of "no", "fal
23820 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e  se", or "off" in
23830 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20   any case or.** 
23840 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67  if the value beg
23850 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72  ins with a numer
23860 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69  ic zero.  If P i
23870 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a  s not a query.**
23880 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20   parameter on F 
23890 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  or if the value 
238a0 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74  of P is does not
238b0 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68   match any of th
238c0 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e  e.** above, then
238d0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
238e0 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75  lean(F,P,B) retu
238f0 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a  rns (B!=0)..**.*
23900 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72  * The sqlite3_ur
23910 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72  i_int64(F,P,D) r
23920 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20  outine converts 
23930 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
23940 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20  nto a.** 64-bit 
23950 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61  signed integer a
23960 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 20  nd returns that 
23970 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66  integer, or D if
23980 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65   P does not.** e
23990 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 61  xist.  If the va
239a0 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65  lue of P is some
239b0 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
239c0 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65   an integer, the
239d0 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74  n.** zero is ret
239e0 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66  urned..** .** If
239f0 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   F is a NULL poi
23a00 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74  nter, then sqlit
23a10 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
23a20 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55  (F,P) returns NU
23a30 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  LL and.** sqlite
23a40 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
23a50 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20  P,B) returns B. 
23a60 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e   If F is not a N
23a70 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a  ULL pointer and.
23a80 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  ** is not a data
23a90 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61  base file pathna
23aa0 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  me pointer that 
23ab0 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e  SQLite passed in
23ac0 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20  to the xOpen.** 
23ad0 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e  VFS method, then
23ae0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
23af0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
23b00 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
23b10 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73  robably.** undes
23b20 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74  irable..*/.const
23b30 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75   char *sqlite3_u
23b40 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e  ri_parameter(con
23b50 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
23b60 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  me, const char *
23b70 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c  zParam);.int sql
23b80 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
23b90 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69  (const char *zFi
23ba0 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  le, const char *
23bb0 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66  zParam, int bDef
23bc0 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69  ault);.sqlite3_i
23bd0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69  nt64 sqlite3_uri
23be0 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61  _int64(const cha
23bf0 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  r*, const char*,
23c00 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
23c10 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
23c20 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41  F: Error Codes A
23c30 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a  nd Messages.**.*
23c40 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
23c50 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61  rrcode() interfa
23c60 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
23c70 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63  umeric [result c
23c80 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  ode] or.** [exte
23c90 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
23ca0 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72  ] for the most r
23cb0 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c  ecent failed sql
23cc0 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a  ite3_* API call.
23cd0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
23ce0 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
23cf0 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61  onnection]. If a
23d00 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20   prior API call 
23d10 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68  failed.** but th
23d20 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50  e most recent AP
23d30 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64  I call succeeded
23d40 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
23d50 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74  ue from.** sqlit
23d60 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20  e3_errcode() is 
23d70 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65  undefined.  ^The
23d80 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
23d90 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69  d_errcode().** i
23da0 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20  nterface is the 
23db0 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74  same except that
23dc0 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72   it always retur
23dd0 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65  ns the .** [exte
23de0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
23df0 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65  ] even when exte
23e00 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
23e10 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65  s are.** disable
23e20 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
23e30 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61  lite3_errmsg() a
23e40 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  nd sqlite3_errms
23e50 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67  g16() return Eng
23e60 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a  lish-language.**
23e70 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72   text that descr
23e80 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20  ibes the error, 
23e90 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
23ea0 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63  or UTF-16 respec
23eb0 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d  tively..** ^(Mem
23ec0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
23ed0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
23ee0 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
23ef0 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54  internally..** T
23f00 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
23f10 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
23f20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65  worry about free
23f30 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a  ing the result..
23f40 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
23f50 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67  error string mig
23f60 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65  ht be overwritte
23f70 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64  n or deallocated
23f80 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e   by.** subsequen
23f90 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72  t calls to other
23fa0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
23fb0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a  e functions.)^.*
23fc0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
23fd0 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65 72  3_errstr() inter
23fe0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
23ff0 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
24000 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64  e text.** that d
24010 65 73 63 72 69 62 65 73 20 74 68 65 20 5b 72 65  escribes the [re
24020 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55  sult code], as U
24030 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72  TF-8..** ^(Memor
24040 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72  y to hold the er
24050 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
24060 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e  ng is managed in
24070 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20  ternally.** and 
24080 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65  must not be free
24090 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
240a0 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68  tion)^..**.** Wh
240b0 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  en the serialize
240c0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
240d0 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74  e] is in use, it
240e0 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a   might be the.**
240f0 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63   case that a sec
24100 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ond error occurs
24110 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74   on a separate t
24120 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e  hread in between
24130 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20  .** the time of 
24140 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20  the first error 
24150 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20  and the call to 
24160 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
24170 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68  ..** When that h
24180 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f  appens, the seco
24190 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65  nd error will be
241a0 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20   reported since 
241b0 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61  these.** interfa
241c0 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72  ces always repor
241d0 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
241e0 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76  t result.  To av
241f0 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63  oid.** this, eac
24200 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74  h thread can obt
24210 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73  ain exclusive us
24220 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  e of the [databa
24230 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
24240 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20  .** by invoking 
24250 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65  [sqlite3_mutex_e
24260 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64  nter]([sqlite3_d
24270 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66  b_mutex](D)) bef
24280 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a  ore beginning.**
24290 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e   to use D and in
242a0 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
242b0 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71  mutex_leave]([sq
242c0 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
242d0 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c  D)) after.** all
242e0 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e   calls to the in
242f0 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20  terfaces listed 
24300 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74  here are complet
24310 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ed..**.** If an 
24320 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20  interface fails 
24330 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55  with SQLITE_MISU
24340 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  SE, that means t
24350 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
24360 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f  was invoked inco
24370 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61  rrectly by the a
24380 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20  pplication.  In 
24390 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a  that case, the.*
243a0 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64  * error code and
243b0 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20   message may or 
243c0 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a  may not be set..
243d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
243e0 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
243f0 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  db);.int sqlite3
24400 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
24410 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
24420 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
24430 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74  te3_errmsg(sqlit
24440 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  e3*);.const void
24450 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
24460 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f  16(sqlite3*);.co
24470 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
24480 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a  3_errstr(int);..
24490 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
244a0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  SQL Statement Ob
244b0 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
244c0 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  : {prepared stat
244d0 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64  ement} {prepared
244e0 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a   statements}.**.
244f0 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
24500 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65  f this object re
24510 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c  presents a singl
24520 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
24530 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
24540 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f  is variously kno
24550 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65  wn as a "prepare
24560 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  d statement" or 
24570 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53  a.** "compiled S
24580 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  QL statement" or
24590 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74   simply as a "st
245a0 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20  atement"..**.** 
245b0 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74  The life of a st
245c0 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67  atement object g
245d0 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69  oes something li
245e0 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
245f0 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61  ol>.** <li> Crea
24600 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  te the object us
24610 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
24620 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20  pare_v2()] or a 
24630 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  related.**      
24640 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69  function..** <li
24650 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  > Bind values to
24660 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   [host parameter
24670 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  s] using the sql
24680 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a  ite3_bind_*().**
24690 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
246a0 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68  ..** <li> Run th
246b0 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67  e SQL by calling
246c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
246d0 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  ] one or more ti
246e0 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73  mes..** <li> Res
246f0 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  et the statement
24700 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
24710 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f  reset()] then go
24720 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f   back.**      to
24730 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69   step 2.  Do thi
24740 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74  s zero or more t
24750 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65  imes..** <li> De
24760 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74  stroy the object
24770 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
24780 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20  finalize()]..** 
24790 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65  </ol>.**.** Refe
247a0 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69  r to documentati
247b0 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
247c0 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66   methods above f
247d0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
247e0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
247f0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24800 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c  sqlite3_stmt sql
24810 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a  ite3_stmt;../*.*
24820 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
24830 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a  time Limits.**.*
24840 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61  * ^(This interfa
24850 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69  ce allows the si
24860 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f  ze of various co
24870 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c  nstructs to be l
24880 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63  imited.** on a c
24890 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e  onnection by con
248a0 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20  nection basis.  
248b0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
248c0 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64  ter is the.** [d
248d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
248e0 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20  on] whose limit 
248f0 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20  is to be set or 
24900 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a  queried.  The.**
24910 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
24920 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  r is one of the 
24930 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  [limit categorie
24940 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  s] that define a
24950 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e  .** class of con
24960 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69  structs to be si
24970 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65  ze limited.  The
24980 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
24990 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c   is the.** new l
249a0 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f  imit for that co
249b0 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a  nstruct.)^.**.**
249c0 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d   ^If the new lim
249d0 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65  it is a negative
249e0 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d   number, the lim
249f0 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e  it is unchanged.
24a00 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c  .** ^(For each l
24a10 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51  imit category SQ
24a20 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41  LITE_LIMIT_<i>NA
24a30 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20  ME</i> there is 
24a40 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  a .** [limits | 
24a50 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
24a60 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70  ].** set at comp
24a70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20  ile-time by a C 
24a80 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
24a90 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69  ro called.** [li
24aa0 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41  mits | SQLITE_MA
24ab0 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a  X_<i>NAME</i>]..
24ac0 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f  ** (The "_LIMIT_
24ad0 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73  " in the name is
24ae0 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41   changed to "_MA
24af0 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65  X_".))^.** ^Atte
24b00 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65  mpts to increase
24b10 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69   a limit above i
24b20 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  ts hard upper bo
24b30 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e  und are.** silen
24b40 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f  tly truncated to
24b50 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20   the hard upper 
24b60 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65  bound..**.** ^Re
24b70 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
24b80 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c  her or not the l
24b90 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64  imit was changed
24ba0 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  , the .** [sqlit
24bb0 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65  e3_limit()] inte
24bc0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
24bd0 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
24be0 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e   the limit..** ^
24bf0 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74  Hence, to find t
24c00 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
24c10 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68   of a limit with
24c20 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c  out changing it,
24c30 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b  .** simply invok
24c40 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  e this interface
24c50 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20   with the third 
24c60 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f  parameter set to
24c70 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74   -1..**.** Run-t
24c80 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69  ime limits are i
24c90 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
24ca0 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  in applications 
24cb0 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62  that manage.** b
24cc0 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e  oth their own in
24cd0 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20  ternal database 
24ce0 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73  and also databas
24cf0 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74  es that are cont
24d00 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74  rolled.** by unt
24d10 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20  rusted external 
24d20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61  sources.  An exa
24d30 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  mple application
24d40 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77   might be a.** w
24d50 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20  eb browser that 
24d60 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61  has its own data
24d70 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e  bases for storin
24d80 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a  g history and.**
24d90 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61   separate databa
24da0 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62  ses controlled b
24db0 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70  y JavaScript app
24dc0 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f  lications downlo
24dd0 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20  aded.** off the 
24de0 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69  Internet.  The i
24df0 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
24e00 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74  s can be given t
24e10 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66  he.** large, def
24e20 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61  ault limits.  Da
24e30 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20  tabases managed 
24e40 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  by external sour
24e50 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69  ces can.** be gi
24e60 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72  ven much smaller
24e70 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64   limits designed
24e80 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65   to prevent a de
24e90 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a  nial of service.
24ea0 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65  ** attack.  Deve
24eb0 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73  lopers might als
24ec0 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68  o want to use th
24ed0 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
24ee0 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20  uthorizer()].** 
24ef0 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72  interface to fur
24f00 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74  ther control unt
24f10 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65  rusted SQL.  The
24f20 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74   size of the dat
24f30 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64  abase.** created
24f40 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64   by an untrusted
24f50 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63   script can be c
24f60 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74  ontained using t
24f70 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f  he.** [max_page_
24f80 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e  count] [PRAGMA].
24f90 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74  .**.** New run-t
24fa0 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ime limit catego
24fb0 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  ries may be adde
24fc0 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
24fd0 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ases..*/.int sql
24fe0 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74  ite3_limit(sqlit
24ff0 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74  e3*, int id, int
25000 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a   newVal);../*.**
25010 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
25020 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f  ime Limit Catego
25030 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ries.** KEYWORDS
25040 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  : {limit categor
25050 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67  y} {*limit categ
25060 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  ories}.**.** The
25070 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  se constants def
25080 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66  ine various perf
25090 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a  ormance limits.*
250a0 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f  * that can be lo
250b0 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d  wered at run-tim
250c0 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  e using [sqlite3
250d0 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68  _limit()]..** Th
250e0 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68  e synopsis of th
250f0 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68  e meanings of th
25100 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73  e various limits
25110 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e   is shown below.
25120 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69  .** Additional i
25130 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76  nformation is av
25140 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69  ailable at [limi
25150 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53  ts | Limits in S
25160 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64  QLite]..**.** <d
25170 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  l>.** [[SQLITE_L
25180 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28  IMIT_LENGTH]] ^(
25190 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
251a0 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
251b0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
251c0 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69  size of any stri
251d0 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61  ng or BLOB or ta
251e0 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65  ble row, in byte
251f0 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  s.<dd>)^.**.** [
25200 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51  [SQLITE_LIMIT_SQ
25210 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74  L_LENGTH]] ^(<dt
25220 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51  >SQLITE_LIMIT_SQ
25230 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  L_LENGTH</dt>.**
25240 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
25250 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51   length of an SQ
25260 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20  L statement, in 
25270 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  bytes.</dd>)^.**
25280 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
25290 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64  IT_COLUMN]] ^(<d
252a0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
252b0 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  OLUMN</dt>.** <d
252c0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
252d0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
252e0 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e  in a table defin
252f0 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a  ition or in the.
25300 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ** result set of
25310 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74   a [SELECT] or t
25320 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
25330 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
25340 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69  an index.** or i
25350 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72  n an ORDER BY or
25360 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65   GROUP BY clause
25370 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
25380 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58  [SQLITE_LIMIT_EX
25390 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74  PR_DEPTH]] ^(<dt
253a0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58  >SQLITE_LIMIT_EX
253b0 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  PR_DEPTH</dt>.**
253c0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
253d0 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61   depth of the pa
253e0 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20  rse tree on any 
253f0 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e  expression.</dd>
25400 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
25410 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
25420 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e  _SELECT]] ^(<dt>
25430 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
25440 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74  POUND_SELECT</dt
25450 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
25460 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
25470 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75  erms in a compou
25480 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  nd SELECT statem
25490 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ent.</dd>)^.**.*
254a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
254b0 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74  _VDBE_OP]] ^(<dt
254c0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  >SQLITE_LIMIT_VD
254d0 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  BE_OP</dt>.** <d
254e0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
254f0 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74  mber of instruct
25500 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61  ions in a virtua
25510 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61  l machine progra
25520 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70  m.** used to imp
25530 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74  lement an SQL st
25540 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c  atement.  This l
25550 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72  imit is not curr
25560 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65  ently.** enforce
25570 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d  d, though that m
25580 69 67 68 74 20 62 65 20 61 64 64 65 64 20 69 6e  ight be added in
25590 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c   some future rel
255a0 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74  ease of.** SQLit
255b0 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  e.</dd>)^.**.** 
255c0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  [[SQLITE_LIMIT_F
255d0 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28  UNCTION_ARG]] ^(
255e0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
255f0 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64  _FUNCTION_ARG</d
25600 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
25610 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
25620 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66  arguments on a f
25630 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  unction.</dd>)^.
25640 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
25650 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20  IMIT_ATTACHED]] 
25660 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
25670 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e  IT_ATTACHED</dt>
25680 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
25690 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41  mum number of [A
256a0 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64  TTACH | attached
256b0 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f   databases].)^</
256c0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
256d0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
256e0 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a  TTERN_LENGTH]].*
256f0 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
25700 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
25710 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  N_LENGTH</dt>.**
25720 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
25730 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70   length of the p
25740 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20  attern argument 
25750 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72  to the [LIKE] or
25760 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61  .** [GLOB] opera
25770 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  tors.</dd>)^.**.
25780 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
25790 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
257a0 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  R]].** ^(<dt>SQL
257b0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
257c0 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a  LE_NUMBER</dt>.*
257d0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
257e0 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f  m index number o
257f0 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72  f any [parameter
25800 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  ] in an SQL stat
25810 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  ement.)^.**.** [
25820 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  [SQLITE_LIMIT_TR
25830 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28  IGGER_DEPTH]] ^(
25840 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
25850 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f  _TRIGGER_DEPTH</
25860 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
25870 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
25880 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72  recursion for tr
25890 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a  iggers.</dd>)^.*
258a0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
258b0 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41  MIT_WORKER_THREA
258c0 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  DS]] ^(<dt>SQLIT
258d0 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54  E_LIMIT_WORKER_T
258e0 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c  HREADS</dt>.** <
258f0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
25900 75 6d 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61  umber of auxilia
25910 72 79 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64  ry worker thread
25920 73 20 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a  s that a single.
25930 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
25940 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72  tement] may star
25950 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  t.</dd>)^.** </d
25960 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
25970 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
25980 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
25990 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
259a0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
259b0 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
259c0 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
259d0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
259e0 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  UMN             
259f0 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
25a00 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58   SQLITE_LIMIT_EX
25a10 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  PR_DEPTH        
25a20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
25a30 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
25a40 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20  OMPOUND_SELECT  
25a50 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
25a60 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
25a70 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20  VDBE_OP         
25a80 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
25a90 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
25aa0 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20  _FUNCTION_ARG   
25ab0 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
25ac0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
25ad0 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20  T_ATTACHED      
25ae0 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
25af0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
25b00 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
25b10 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23  LENGTH       8.#
25b20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
25b30 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
25b40 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a  BER           9.
25b50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
25b60 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
25b70 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30  TH            10
25b80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
25b90 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52  LIMIT_WORKER_THR
25ba0 45 41 44 53 20 20 20 20 20 20 20 20 20 20 20 31  EADS           1
25bb0 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  1../*.** CAPI3RE
25bc0 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20  F: Compiling An 
25bd0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL Statement.**
25be0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
25bf0 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c  statement compil
25c00 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65  er}.**.** To exe
25c10 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72  cute an SQL quer
25c20 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74  y, it must first
25c30 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74   be compiled int
25c40 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a  o a byte-code.**
25c50 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f   program using o
25c60 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ne of these rout
25c70 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ines..**.** The 
25c80 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20  first argument, 
25c90 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61  "db", is a [data
25ca0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
25cb0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
25cc0 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73  .** prior succes
25cd0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
25ce0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
25cf0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
25d00 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
25d10 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68  3_open16()].  Th
25d20 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
25d30 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68  ction must not h
25d40 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e  ave been closed.
25d50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
25d60 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71  d argument, "zSq
25d70 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65  l", is the state
25d80 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
25d90 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20  led, encoded.** 
25da0 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
25db0 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20  or UTF-16.  The 
25dc0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
25dd0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
25de0 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e  epare_v2().** in
25df0 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46  terfaces use UTF
25e00 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  -8, and sqlite3_
25e10 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20  prepare16() and 
25e20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
25e30 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54  6_v2().** use UT
25e40 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  F-16..**.** ^If 
25e50 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65  the nByte argume
25e60 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  nt is less than 
25e70 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20  zero, then zSql 
25e80 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68  is read up to th
25e90 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20  e.** first zero 
25ea0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20  terminator. ^If 
25eb0 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67  nByte is non-neg
25ec0 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69  ative, then it i
25ed0 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
25ee0 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65   number of  byte
25ef0 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
25f00 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69  .  ^When nByte i
25f10 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
25f20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69  the.** zSql stri
25f30 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65  ng ends at eithe
25f40 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30  r the first '\00
25f50 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63  0' or '\u0000' c
25f60 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74  haracter or.** t
25f70 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65  he nByte-th byte
25f80 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65  , whichever come
25f90 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20  s first. If the 
25fa0 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20  caller knows.** 
25fb0 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65  that the supplie
25fc0 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d  d string is nul-
25fd0 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e  terminated, then
25fe0 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c   there is a smal
25ff0 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65  l.** performance
26000 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65   advantage to be
26010 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69   gained by passi
26020 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61  ng an nByte para
26030 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73  meter that.** is
26040 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75   equal to the nu
26050 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
26060 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
26070 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f  g <i>including</
26080 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65  i>.** the nul-te
26090 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20 61  rminator bytes a
260a0 73 20 74 68 69 73 20 73 61 76 65 73 20 53 51 4c  s this saves SQL
260b0 69 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 20  ite from having 
260c0 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70  to.** make a cop
260d0 79 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20 73  y of the input s
260e0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  tring..**.** ^If
260f0 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e   pzTail is not N
26100 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c  ULL then *pzTail
26110 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
26120 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62  t to the first b
26130 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20  yte.** past the 
26140 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74  end of the first
26150 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
26160 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72  n zSql.  These r
26170 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20  outines only.** 
26180 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73  compile the firs
26190 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  t statement in z
261a0 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20  Sql, so *pzTail 
261b0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
261c0 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61   to.** what rema
261d0 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a  ins uncompiled..
261e0 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69  **.** ^*ppStmt i
261f0 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
26200 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70  to a compiled [p
26210 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26220 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a  t] that can be.*
26230 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67  * executed using
26240 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
26250 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73  ].  ^If there is
26260 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74   an error, *ppSt
26270 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20  mt is set.** to 
26280 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69  NULL.  ^If the i
26290 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69  nput text contai
262a0 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68  ns no SQL (if th
262b0 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d  e input is an em
262c0 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72  pty.** string or
262d0 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e   a comment) then
262e0 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20   *ppStmt is set 
262f0 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20  to NULL..** The 
26300 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72  calling procedur
26310 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  e is responsible
26320 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68   for deleting th
26330 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51  e compiled.** SQ
26340 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  L statement usin
26350 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
26360 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20  ize()] after it 
26370 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
26380 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20  h it..** ppStmt 
26390 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e  may not be NULL.
263a0 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65  .**.** ^On succe
263b0 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ss, the sqlite3_
263c0 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79  prepare() family
263d0 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74   of routines ret
263e0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b  urn [SQLITE_OK];
263f0 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e  .** otherwise an
26400 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
26410 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
26420 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
26430 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71  pare_v2() and sq
26440 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
26450 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20  v2() interfaces 
26460 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64  are.** recommend
26470 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70  ed for all new p
26480 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f  rograms. The two
26490 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65   older interface
264a0 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a  s are retained.*
264b0 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  * for backwards 
264c0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62  compatibility, b
264d0 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20  ut their use is 
264e0 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20  discouraged..** 
264f0 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
26500 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65  erfaces, the pre
26510 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
26520 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72  ** that is retur
26530 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ned (the [sqlite
26540 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20  3_stmt] object) 
26550 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20  contains a copy 
26560 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  of the.** origin
26570 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69  al SQL text. Thi
26580 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71  s causes the [sq
26590 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e  lite3_step()] in
265a0 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65  terface to.** be
265b0 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79  have differently
265c0 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a   in three ways:.
265d0 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
265e0 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  i>.** ^If the da
265f0 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
26600 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f  anges, instead o
26610 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  f returning [SQL
26620 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69  ITE_SCHEMA] as i
26630 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64  t.** always used
26640 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33   to do, [sqlite3
26650 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75  _step()] will au
26660 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
26670 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a  mpile the SQL.**
26680 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
26690 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61  ry to run it aga
266a0 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b  in. As many as [
266b0 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d  SQLITE_MAX_SCHEM
266c0 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72  A_RETRY].** retr
266d0 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62  ies will occur b
266e0 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74  efore sqlite3_st
266f0 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e  ep() gives up an
26700 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72  d returns an err
26710 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  or..** </li>.**.
26720 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e  ** <li>.** ^When
26730 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
26740 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
26750 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f  )] will return o
26760 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c  ne of the detail
26770 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  ed.** [error cod
26780 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  es] or [extended
26790 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20   error codes].  
267a0 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61  ^The legacy beha
267b0 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a  vior was that.**
267c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
267d0 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74  ] would only ret
267e0 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53  urn a generic [S
267f0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73  QLITE_ERROR] res
26800 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20  ult code.** and 
26810 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
26820 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61  would have to ma
26830 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ke a second call
26840 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
26850 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65  et()].** in orde
26860 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e  r to find the un
26870 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f  derlying cause o
26880 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57  f the problem. W
26890 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65  ith the "v2" pre
268a0 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  pare.** interfac
268b0 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69  es, the underlyi
268c0 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68  ng reason for th
268d0 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  e error is retur
268e0 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  ned immediately.
268f0 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
26900 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
26910 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62  specific value b
26920 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74  ound to [paramet
26930 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65  er | host parame
26940 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20  ter] in the .** 
26950 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67  WHERE clause mig
26960 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
26970 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
26980 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74   plan for a stat
26990 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74  ement,.** then t
269a0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c  he statement wil
269b0 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
269c0 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61  ly recompiled, a
269d0 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62  s if there had b
269e0 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61  een .** a schema
269f0 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20   change, on the 
26a00 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f  first  [sqlite3_
26a10 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c  step()] call fol
26a20 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67  lowing any chang
26a30 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  e.** to the [sql
26a40 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
26a50 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68   bindings] of th
26a60 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20  at [parameter]. 
26a70 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69  .** ^The specifi
26a80 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45  c value of WHERE
26a90 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74  -clause [paramet
26aa0 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  er] might influe
26ab0 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69  nce the .** choi
26ac0 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
26ad0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
26ae0 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61  r is the left-ha
26af0 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49  nd side of a [LI
26b00 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d  KE].** or [GLOB]
26b10 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20   operator or if 
26b20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
26b30 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20   compared to an 
26b40 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a  indexed column.*
26b50 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54  * and the [SQLIT
26b60 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20  E_ENABLE_STAT3] 
26b70 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
26b80 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
26b90 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c  ** </li>.** </ol
26ba0 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  >.*/.int sqlite3
26bb0 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69  _prepare(.  sqli
26bc0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
26bd0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
26be0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
26bf0 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
26c00 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
26c10 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
26c20 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
26c30 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
26c40 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
26c50 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
26c60 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
26c70 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
26c80 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
26c90 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
26ca0 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
26cb0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
26cc0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
26cd0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
26ce0 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
26cf0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a  te3_prepare_v2(.
26d00 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
26d10 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
26d20 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
26d30 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
26d40 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
26d50 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
26d60 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
26d70 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
26d80 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
26d90 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
26da0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
26db0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
26dc0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
26dd0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
26de0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
26df0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
26e00 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
26e10 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
26e20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
26e30 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
26e40 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  e16(.  sqlite3 *
26e50 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
26e60 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
26e70 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
26e80 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
26e90 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
26ea0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
26eb0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
26ec0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
26ed0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
26ee0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
26ef0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
26f00 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
26f10 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
26f20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
26f30 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
26f40 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
26f50 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
26f60 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
26f70 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
26f80 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20  prepare16_v2(.  
26f90 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
26fa0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
26fb0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
26fc0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
26fd0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
26fe0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
26ff0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
27000 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
27010 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
27020 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
27030 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
27040 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
27050 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
27060 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
27070 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
27080 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
27090 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
270a0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
270b0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a  f zSql */.);../*
270c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
270d0 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65  trieving Stateme
270e0 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68  nt SQL.**.** ^Th
270f0 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
27100 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72   be used to retr
27110 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70  ieve a saved cop
27120 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61  y of the origina
27130 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73  l.** SQL text us
27140 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b  ed to create a [
27150 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27160 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74  nt] if that stat
27170 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d  ement was.** com
27180 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68  piled using eith
27190 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
271a0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
271b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
271c0 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  v2()]..*/.const 
271d0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71  char *sqlite3_sq
271e0 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  l(sqlite3_stmt *
271f0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
27200 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
27210 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
27220 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68  tement Writes Th
27230 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a  e Database.**.**
27240 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
27250 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69  mt_readonly(X) i
27260 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
27270 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29   true (non-zero)
27280 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20   if.** and only 
27290 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  if the [prepared
272a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61   statement] X ma
272b0 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68  kes no direct ch
272c0 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20  anges to.** the 
272d0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64  content of the d
272e0 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a  atabase file..**
272f0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61  .** Note that [a
27300 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
27310 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
27320 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c  ] or.** [virtual
27330 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63   tables] might c
27340 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
27350 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73  se indirectly as
27360 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e 20   a side effect. 
27370 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70   .** ^(For examp
27380 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63  le, if an applic
27390 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20  ation defines a 
273a0 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29  function "eval()
273b0 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73  " that .** calls
273c0 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
273d0 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c  ], then the foll
273e0 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  owing SQL statem
273f0 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61  ent would.** cha
27400 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
27410 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69   file through si
27420 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a  de-effects:.**.*
27430 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
27440 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54  re>.**    SELECT
27450 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52   eval('DELETE FR
27460 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b  OM t1') FROM t2;
27470 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
27480 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75  kquote>.**.** Bu
27490 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b 53  t because the [S
274a0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
274b0 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
274c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
274d0 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20  le.** directly, 
274e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
274f0 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74  donly() would st
27500 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e  ill return true.
27510 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61  )^.**.** ^Transa
27520 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74  ction control st
27530 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73  atements such as
27540 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49   [BEGIN], [COMMI
27550 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a  T], [ROLLBACK],.
27560 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20  ** [SAVEPOINT], 
27570 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61  and [RELEASE] ca
27580 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  use sqlite3_stmt
27590 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72  _readonly() to r
275a0 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73  eturn true,.** s
275b0 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d 65  ince the stateme
275c0 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64  nts themselves d
275d0 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d  o not actually m
275e0 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61  odify the databa
275f0 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72  se but.** rather
27600 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68   they control th
27610 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e  e timing of when
27620 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74   other statement
27630 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a  s modify the .**
27640 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65   database.  ^The
27650 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44   [ATTACH] and [D
27660 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74  ETACH] statement
27670 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20  s also cause.** 
27680 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
27690 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72  donly() to retur
276a0 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68  n true since, wh
276b0 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d  ile those statem
276c0 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ents.** change t
276d0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
276e0 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 63   of a database c
276f0 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20  onnection, they 
27700 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20  do not make .** 
27710 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63  changes to the c
27720 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61  ontent of the da
27730 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20  tabase files on 
27740 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  disk..*/.int sql
27750 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
27760 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ly(sqlite3_stmt 
27770 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
27780 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
27790 69 6e 65 20 49 66 20 41 20 50 72 65 70 61 72 65  ine If A Prepare
277a0 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20  d Statement Has 
277b0 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a 2a  Been Reset.**.**
277c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
277d0 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72  mt_busy(S) inter
277e0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75  face returns tru
277f0 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20  e (non-zero) if 
27800 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
27810 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61   statement] S ha
27820 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 61  s been stepped a
27830 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69  t least once usi
27840 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
27850 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 73  step(S)] but has
27860 20 6e 6f 74 20 72 75 6e 20 74 6f 20 63 6f 6d 70   not run to comp
27870 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f 72 20 68 61  letion and/or ha
27880 73 20 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e 20 72  s not .** been r
27890 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  eset using [sqli
278a0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20  te3_reset(S)].  
278b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
278c0 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74  t_busy(S).** int
278d0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 66  erface returns f
278e0 61 6c 73 65 20 69 66 20 53 20 69 73 20 61 20 4e  alse if S is a N
278f0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66  ULL pointer.  If
27900 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20   S is not a .** 
27910 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64  NULL pointer and
27920 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65   is not a pointe
27930 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72  r to a valid [pr
27940 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27950 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65  ].** object, the
27960 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
27970 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
27980 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72  probably undesir
27990 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  able..**.** This
279a0 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
279b0 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e  e used in combin
279c0 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e  ation [sqlite3_n
279d0 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74  ext_stmt()].** t
279e0 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65  o locate all pre
279f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
27a00 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
27a10 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20   a database .** 
27a20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
27a30 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62  are in need of b
27a40 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69  eing reset.  Thi
27a50 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a  s can be used,.*
27a60 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  * for example, i
27a70 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75  n diagnostic rou
27a80 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20  tines to search 
27a90 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a  for prepared .**
27aa0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
27ab0 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74   are holding a t
27ac0 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e  ransaction open.
27ad0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
27ae0 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65  stmt_busy(sqlite
27af0 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
27b00 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d   CAPI3REF: Dynam
27b10 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c  ically Typed Val
27b20 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  ue Object.** KEY
27b30 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65  WORDS: {protecte
27b40 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
27b50 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   {unprotected sq
27b60 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a  lite3_value}.**.
27b70 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74  ** SQLite uses t
27b80 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
27b90 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65   object to repre
27ba0 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a  sent all values.
27bb0 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73  ** that can be s
27bc0 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62  tored in a datab
27bd0 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74  ase table. SQLit
27be0 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74  e uses dynamic t
27bf0 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65  yping.** for the
27c00 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65   values it store
27c10 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72  s.  ^Values stor
27c20 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61  ed in sqlite3_va
27c30 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63  lue objects.** c
27c40 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20  an be integers, 
27c50 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
27c60 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20  alues, strings, 
27c70 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a  BLOBs, or NULL..
27c80 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33  **.** An sqlite3
27c90 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61  _value object ma
27ca0 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f  y be either "pro
27cb0 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72  tected" or "unpr
27cc0 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d  otected"..** Som
27cd0 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  e interfaces req
27ce0 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64  uire a protected
27cf0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20   sqlite3_value. 
27d00 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   Other interface
27d10 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74  s.** will accept
27d20 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63   either a protec
27d30 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ted or an unprot
27d40 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
27d50 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e  lue..** Every in
27d60 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63  terface that acc
27d70 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c  epts sqlite3_val
27d80 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65  ue arguments spe
27d90 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65  cifies.** whethe
27da0 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75  r or not it requ
27db0 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64  ires a protected
27dc0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
27dd0 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20  **.** The terms 
27de0 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20  "protected" and 
27df0 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65  "unprotected" re
27e00 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f  fer to whether o
27e10 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78  r not.** a mutex
27e20 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e   is held.  An in
27e30 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20  ternal mutex is 
27e40 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65  held for a prote
27e50 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
27e60 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74  value object but
27e70 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c   no mutex is hel
27e80 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  d for an unprote
27e90 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
27ea0 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49  value object.  I
27eb0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
27ec0 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c  iled to be singl
27ed0 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77  e-threaded.** (w
27ee0 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  ith [SQLITE_THRE
27ef0 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69  ADSAFE=0] and wi
27f00 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65  th [sqlite3_thre
27f10 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e  adsafe()] return
27f20 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20  ing 0).** or if 
27f30 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e  SQLite is run in
27f40 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20   one of reduced 
27f50 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20  mutex modes .** 
27f60 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
27f70 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20  INGLETHREAD] or 
27f80 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
27f90 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74  ULTITHREAD].** t
27fa0 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20  hen there is no 
27fb0 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
27fc0 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
27fd0 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
27fe0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
27ff0 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20  bjects and they 
28000 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65  can be used inte
28010 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f  rchangeably.  Ho
28020 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61  wever,.** for ma
28030 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61  ximum code porta
28040 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63  bility it is rec
28050 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
28060 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74  plications.** st
28070 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73  ill make the dis
28080 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
28090 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
280a0 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
280b0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
280c0 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f  cts even when no
280d0 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69  t strictly requi
280e0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  red..**.** ^The 
280f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
28100 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70  jects that are p
28110 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74  assed as paramet
28120 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ers into the.** 
28130 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
28140 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  f [application-d
28150 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
28160 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63  ions] are protec
28170 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ted..** ^The sql
28180 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
28190 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
281a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
281b0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70  _value()] is unp
281c0 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70  rotected..** Unp
281d0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
281e0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d  _value objects m
281f0 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
28200 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  with.** [sqlite3
28210 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
28220 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
28230 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  nd_value()]..** 
28240 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
28250 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  ue_blob | sqlite
28260 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20  3_value_type()] 
28270 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74  family of.** int
28280 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
28290 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
282a0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e  3_value objects.
282b0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
282c0 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76  ct Mem sqlite3_v
282d0 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  alue;../*.** CAP
282e0 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74  I3REF: SQL Funct
282f0 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65  ion Context Obje
28300 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e  ct.**.** The con
28310 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e  text in which an
28320 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78   SQL function ex
28330 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64  ecutes is stored
28340 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   in an.** sqlite
28350 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
28360 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f  .  ^A pointer to
28370 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74   an sqlite3_cont
28380 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73  ext object.** is
28390 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61   always first pa
283a0 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c  rameter to [appl
283b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
283c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  SQL functions]..
283d0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
283e0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
283f0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
28400 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73  tation will pass
28410 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72   this.** pointer
28420 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61   through into ca
28430 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
28440 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c  result_int | sql
28450 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a  ite3_result()],.
28460 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72  ** [sqlite3_aggr
28470 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d  egate_context()]
28480 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  , [sqlite3_user_
28490 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  data()],.** [sql
284a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
284b0 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69  handle()], [sqli
284c0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
284d0 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73  )],.** and/or [s
284e0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
284f0 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  ta()]..*/.typede
28500 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
28510 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33  _context sqlite3
28520 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a  _context;../*.**
28530 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69   CAPI3REF: Bindi
28540 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65  ng Values To Pre
28550 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73  pared Statements
28560 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68  .** KEYWORDS: {h
28570 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  ost parameter} {
28580 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d  host parameters}
28590 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
285a0 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52   name}.** KEYWOR
285b0 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  DS: {SQL paramet
285c0 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  er} {SQL paramet
285d0 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20  ers} {parameter 
285e0 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e  binding}.**.** ^
285f0 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  (In the SQL stat
28600 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74  ement text input
28610 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   to [sqlite3_pre
28620 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69  pare_v2()] and i
28630 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20  ts variants,.** 
28640 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20  literals may be 
28650 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70  replaced by a [p
28660 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d  arameter] that m
28670 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f  atches one of fo
28680 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c  llowing.** templ
28690 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ates:.**.** <ul>
286a0 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c  .** <li>  ?.** <
286b0 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69  li>  ?NNN.** <li
286c0 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  :VVV.** <li> 
286d0 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24   @VVV.** <li>  $
286e0 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VVV.** </ul>.**.
286f0 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61  ** In the templa
28700 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72  tes above, NNN r
28710 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74  epresents an int
28720 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a  eger literal,.**
28730 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65   and VVV represe
28740 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65  nts an alphanume
28750 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29  ric identifier.)
28760 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f  ^  ^The values o
28770 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d  f these.** param
28780 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c  eters (also call
28790 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74  ed "host paramet
287a0 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51  er names" or "SQ
287b0 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a  L parameters").*
287c0 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69  * can be set usi
287d0 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
287e0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
287f0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a   defined here..*
28800 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
28810 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
28820 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
28830 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77   routines is alw
28840 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  ays.** a pointer
28850 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
28860 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65  _stmt] object re
28870 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b  turned from.** [
28880 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
28890 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  v2()] or its var
288a0 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  iants..**.** ^Th
288b0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
288c0 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
288d0 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65  f the SQL parame
288e0 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a  ter to be set..*
288f0 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  * ^The leftmost 
28900 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61  SQL parameter ha
28910 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e  s an index of 1.
28920 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65    ^When the same
28930 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61   named.** SQL pa
28940 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20  rameter is used 
28950 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20  more than once, 
28960 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
28970 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65  quent.** occurre
28980 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61  nces have the sa
28990 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20  me index as the 
289a0 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65  first occurrence
289b0 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20  ..** ^The index 
289c0 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  for named parame
289d0 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b  ters can be look
289e0 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a  ed up using the.
289f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
28a00 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
28a10 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72  ()] API if desir
28a20 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a  ed.  ^The index.
28a30 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61  ** for "?NNN" pa
28a40 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20  rameters is the 
28a50 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a  value of NNN..**
28a60 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20   ^The NNN value 
28a70 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20  must be between 
28a80 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74  1 and the [sqlit
28a90 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70  e3_limit()].** p
28aa0 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45  arameter [SQLITE
28ab0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
28ac0 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74  NUMBER] (default
28ad0 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a   value: 999)..**
28ae0 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61  .** ^The third a
28af0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76  rgument is the v
28b00 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20  alue to bind to 
28b10 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
28b20 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20  * ^If the third 
28b30 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
28b40 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
28b50 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
28b60 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20  _text16().** or 
28b70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
28b80 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  b() is a NULL po
28b90 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 66  inter then the f
28ba0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a  ourth parameter.
28bb0 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e  ** is ignored an
28bc0 64 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74  d the end result
28bd0 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20   is the same as 
28be0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
28bf0 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  l()..**.** ^(In 
28c00 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74  those routines t
28c10 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74  hat have a fourt
28c20 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20  h argument, its 
28c30 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
28c40 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
28c50 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
28c60 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20  .  To be clear: 
28c70 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  the value is the
28c80 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75  .** number of <u
28c90 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68  >bytes</u> in th
28ca0 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65  e value, not the
28cb0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
28cc0 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20  cters.)^.** ^If 
28cd0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
28ce0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
28cf0 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73  bind_text() or s
28d00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
28d10 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74  16().** is negat
28d20 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65  ive, then the le
28d30 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69  ngth of the stri
28d40 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  ng is.** the num
28d50 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20  ber of bytes up 
28d60 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
28d70 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  o terminator..**
28d80 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   If the fourth p
28d90 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
28da0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20  te3_bind_blob() 
28db0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
28dc0 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f  n.** the behavio
28dd0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
28de0 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61  ** If a non-nega
28df0 74 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 61  tive fourth para
28e00 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 65  meter is provide
28e10 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  d to sqlite3_bin
28e20 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73  d_text().** or s
28e30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
28e40 31 36 28 29 20 74 68 65 6e 20 74 68 61 74 20 70  16() then that p
28e50 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65  arameter must be
28e60 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74   the byte offset
28e70 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55  .** where the NU
28e80 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75  L terminator wou
28e90 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e  ld occur assumin
28ea0 67 20 74 68 65 20 73 74 72 69 6e 67 20 77 65 72  g the string wer
28eb0 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61  e NUL.** termina
28ec0 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c  ted.  If any NUL
28ed0 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75   characters occu
28ee0 72 20 61 74 20 62 79 74 65 20 6f 66 66 73 65 74  r at byte offset
28ef0 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20  s less than .** 
28f00 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
28f10 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
28f20 72 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  r then the resul
28f30 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75  ting string valu
28f40 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69  e will.** contai
28f50 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e  n embedded NULs.
28f60 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20    The result of 
28f70 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f  expressions invo
28f80 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a  lving strings.**
28f90 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e   with embedded N
28fa0 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ULs is undefined
28fb0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66  ..**.** ^The fif
28fc0 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
28fd0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
28fe0 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  (), sqlite3_bind
28ff0 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20  _text(), and.** 
29000 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
29010 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72  t16() is a destr
29020 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69  uctor used to di
29030 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f  spose of the BLO
29040 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61  B or.** string a
29050 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20  fter SQLite has 
29060 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
29070 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74  .  ^The destruct
29080 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20  or is called.** 
29090 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
290a0 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  e BLOB or string
290b0 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c   even if the cal
290c0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  l to sqlite3_bin
290d0 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c  d_blob(),.** sql
290e0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
290f0 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  , or sqlite3_bin
29100 64 5f 74 65 78 74 31 36 28 29 20 66 61 69 6c 73  d_text16() fails
29110 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .  .** ^If the f
29120 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73  ifth argument is
29130 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20  .** the special 
29140 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54  value [SQLITE_ST
29150 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69  ATIC], then SQLi
29160 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
29170 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  the.** informati
29180 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c  on is in static,
29190 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65   unmanaged space
291a0 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65   and does not ne
291b0 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a  ed to be freed..
291c0 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68  ** ^If the fifth
291d0 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68   argument has th
291e0 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  e value [SQLITE_
291f0 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e  TRANSIENT], then
29200 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  .** SQLite makes
29210 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
29220 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74   copy of the dat
29230 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62  a immediately, b
29240 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c  efore.** the sql
29250 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
29260 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a  utine returns..*
29270 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
29280 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
29290 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20  ) routine binds 
292a0 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68  a BLOB of length
292b0 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69   N that.** is fi
292c0 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73  lled with zeroes
292d0 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75  .  ^A zeroblob u
292e0 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75  ses a fixed amou
292f0 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20  nt of memory.** 
29300 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72  (just an integer
29310 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a   to hold its siz
29320 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62  e) while it is b
29330 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a  eing processed..
29340 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65  ** Zeroblobs are
29350 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72   intended to ser
29360 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65  ve as placeholde
29370 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f  rs for BLOBs who
29380 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73  se.** content is
29390 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75   later written u
293a0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
293b0 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63  _blob_open | inc
293c0 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f  remental BLOB I/
293d0 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20  O] routines..** 
293e0 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75  ^A negative valu
293f0 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c  e for the zerobl
29400 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20  ob results in a 
29410 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
29420 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20  ..**.** ^If any 
29430 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  of the sqlite3_b
29440 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
29450 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68   are called with
29460 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
29470 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70  ** for the [prep
29480 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
29490 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72  or with a prepar
294a0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72  ed statement for
294b0 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74   which.** [sqlit
294c0 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62  e3_step()] has b
294d0 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20  een called more 
294e0 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73  recently than [s
294f0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c  qlite3_reset()],
29500 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c  .** then the cal
29510 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  l will return [S
29520 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
29530 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62  If any sqlite3_b
29540 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ind_().** routin
29550 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70  e is passed a [p
29560 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29570 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e  t] that has been
29580 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a   finalized, the.
29590 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  ** result is und
295a0 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
295b0 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a  bly harmful..**.
295c0 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65  ** ^Bindings are
295d0 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20   not cleared by 
295e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  the [sqlite3_res
295f0 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a  et()] routine..*
29600 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d  * ^Unbound param
29610 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70  eters are interp
29620 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a  reted as NULL..*
29630 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
29640 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65  3_bind_* routine
29650 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
29660 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
29670 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20  or an.** [error 
29680 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e  code] if anythin
29690 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a  g goes wrong..**
296a0 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d   ^[SQLITE_RANGE]
296b0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
296c0 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  the parameter.**
296d0 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
296e0 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54   range.  ^[SQLIT
296f0 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75  E_NOMEM] is retu
29700 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29  rned if malloc()
29710 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65   fails..**.** Se
29720 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
29730 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
29740 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  count()],.** [sq
29750 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
29760 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
29770 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
29780 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
29790 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
297a0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c  e3_bind_blob(sql
297b0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
297c0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
297d0 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
297e0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
297f0 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71  3_bind_double(sq
29800 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
29810 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73  , double);.int s
29820 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28  qlite3_bind_int(
29830 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
29840 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  nt, int);.int sq
29850 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34  lite3_bind_int64
29860 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29870 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  int, sqlite3_int
29880 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  64);.int sqlite3
29890 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74  _bind_null(sqlit
298a0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
298b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
298c0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
298d0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
298e0 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  char*, int n, vo
298f0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
29900 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
29910 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
29920 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
29930 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
29940 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
29950 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76  t sqlite3_bind_v
29960 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
29970 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73  t*, int, const s
29980 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
29990 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
299a0 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
299b0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
299c0 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t n);../*.** CAP
299d0 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
299e0 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a   SQL Parameters.
299f0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
29a00 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ine can be used 
29a10 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
29a20 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d  er of [SQL param
29a30 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b  eters].** in a [
29a40 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29a50 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65  nt].  SQL parame
29a60 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20  ters are tokens 
29a70 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22  of the.** form "
29a80 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41  ?", "?NNN", ":AA
29a90 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22  A", "$AAA", or "
29aa0 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65  @AAA" that serve
29ab0 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64   as.** placehold
29ac0 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74  ers for values t
29ad0 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33  hat are [sqlite3
29ae0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75  _bind_blob | bou
29af0 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61  nd].** to the pa
29b00 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61  rameters at a la
29b10 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ter time..**.** 
29b20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61  ^(This routine a
29b30 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20  ctually returns 
29b40 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
29b50 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d   largest (rightm
29b60 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65  ost).** paramete
29b70 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73  r. For all forms
29b80 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68   except ?NNN, th
29b90 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f  is will correspo
29ba0 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d  nd to the.** num
29bb0 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61  ber of unique pa
29bc0 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61  rameters.  If pa
29bd0 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
29be0 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73  ?NNN form are us
29bf0 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79  ed,.** there may
29c00 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20   be gaps in the 
29c10 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  list.)^.**.** Se
29c20 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
29c30 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
29c40 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
29c50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
29c60 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
29c70 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
29c80 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
29c90 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ndex()]..*/.int 
29ca0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
29cb0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c  ameter_count(sql
29cc0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
29cd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61  .** CAPI3REF: Na
29ce0 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72  me Of A Host Par
29cf0 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68  ameter.**.** ^Th
29d00 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  e sqlite3_bind_p
29d10 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c  arameter_name(P,
29d20 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  N) interface ret
29d30 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  urns.** the name
29d40 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51   of the N-th [SQ
29d50 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20  L parameter] in 
29d60 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
29d70 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
29d80 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20  (SQL parameters 
29d90 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e  of the form "?NN
29da0 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
29db0 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
29dc0 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20  .** have a name 
29dd0 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72  which is the str
29de0 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  ing "?NNN" or ":
29df0 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
29e00 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70  r "$AAA".** resp
29e10 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20  ectively..** In 
29e20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
29e30 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20   initial ":" or 
29e40 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f  "$" or "@" or "?
29e50 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64  ".** is included
29e60 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   as part of the 
29e70 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61  name.)^.** ^Para
29e80 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
29e90 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61  rm "?" without a
29ea0 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67   following integ
29eb0 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a  er have no name.
29ec0 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72  ** and are refer
29ed0 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c  red to as "namel
29ee0 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f  ess" or "anonymo
29ef0 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a  us parameters"..
29f00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
29f10 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20   host parameter 
29f20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
29f30 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20  1, not 0..**.** 
29f40 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20  ^If the value N 
29f50 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  is out of range 
29f60 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70  or if the N-th p
29f70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e  arameter is.** n
29f80 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55  ameless, then NU
29f90 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  LL is returned. 
29fa0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
29fb0 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61  tring is.** alwa
29fc0 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f  ys in UTF-8 enco
29fd0 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ding even if the
29fe0 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
29ff0 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   was.** original
2a000 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ly specified as 
2a010 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74  UTF-16 in [sqlit
2a020 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
2a030 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  or.** [sqlite3_p
2a040 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
2a050 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2a060 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2a070 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
2a080 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2a090 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
2a0a0 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
2a0b0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2a0c0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2a0d0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
2a0e0 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  *sqlite3_bind_pa
2a0f0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c  rameter_name(sql
2a100 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
2a110 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2a120 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61  F: Index Of A Pa
2a130 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47  rameter With A G
2a140 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20  iven Name.**.** 
2a150 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65  ^Return the inde
2a160 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61  x of an SQL para
2a170 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20  meter given its 
2a180 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69  name.  ^The.** i
2a190 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72  ndex value retur
2a1a0 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20  ned is suitable 
2a1b0 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73  for use as the s
2a1c0 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74  econd.** paramet
2a1d0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  er to [sqlite3_b
2a1e0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
2a1f0 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65  _bind()].  ^A ze
2a200 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  ro.** is returne
2a210 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67  d if no matching
2a220 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f   parameter is fo
2a230 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  und.  ^The param
2a240 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73  eter.** name mus
2a250 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54  t be given in UT
2a260 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20  F-8 even if the 
2a270 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
2a280 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72  nt.** was prepar
2a290 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74  ed from UTF-16 t
2a2a0 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ext using [sqlit
2a2b0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2a2c0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
2a2d0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
2a2e0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
2a2f0 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
2a300 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2a310 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
2a320 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2a330 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2a340 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  x()]..*/.int sql
2a350 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2a360 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65  ter_index(sqlite
2a370 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63  3_stmt*, const c
2a380 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a  har *zName);../*
2a390 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2a3a0 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73  set All Bindings
2a3b0 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53   On A Prepared S
2a3c0 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e  tatement.**.** ^
2a3d0 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20  Contrary to the 
2a3e0 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e  intuition of man
2a3f0 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  y, [sqlite3_rese
2a400 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65  t()] does not re
2a410 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  set.** the [sqli
2a420 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
2a430 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b  bindings] on a [
2a440 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a450 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69  nt]..** ^Use thi
2a460 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73  s routine to res
2a470 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61  et all host para
2a480 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a  meters to NULL..
2a490 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
2a4a0 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  lear_bindings(sq
2a4b0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2a4c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2a4d0 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73  umber Of Columns
2a4e0 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
2a4f0 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
2a500 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
2a510 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
2a520 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20  lt set returned 
2a530 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  by the.** [prepa
2a540 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
2a550 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
2a560 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74  turns 0 if pStmt
2a570 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74   is an SQL.** st
2a580 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65  atement that doe
2a590 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74  s not return dat
2a5a0 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61  a (for example a
2a5b0 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a  n [UPDATE])..**.
2a5c0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2a5d0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2a5e0 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ()].*/.int sqlit
2a5f0 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
2a600 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2a610 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2a620 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61  I3REF: Column Na
2a630 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mes In A Result 
2a640 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  Set.**.** ^These
2a650 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2a660 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e   the name assign
2a670 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c  ed to a particul
2a680 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20  ar column.** in 
2a690 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
2a6a0 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  f a [SELECT] sta
2a6b0 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71  tement.  ^The sq
2a6c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2a6d0 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
2a6e0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2a6f0 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
2a700 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
2a710 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ring.** and sqli
2a720 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
2a730 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  6() returns a po
2a740 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
2a750 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
2a760 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
2a770 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2a780 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61  er is the [prepa
2a790 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
2a7a0 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  * that implement
2a7b0 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73  s the [SELECT] s
2a7c0 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73  tatement. ^The s
2a7d0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2a7e0 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  is the.** column
2a7f0 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c   number.  ^The l
2a800 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  eftmost column i
2a810 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a  s number 0..**.*
2a820 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
2a830 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69  string pointer i
2a840 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69  s valid until ei
2a850 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72  ther the [prepar
2a860 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
2a870 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79   is destroyed by
2a880 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2a890 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
2a8a0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2a8b0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
2a8c0 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74   reprepared by t
2a8d0 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f  he first call to
2a8e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2a8f0 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ] for a particul
2a900 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74  ar run.** or unt
2a910 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c  il the next call
2a920 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
2a930 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20  olumn_name() or 
2a940 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2a950 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73  ame16() on the s
2a960 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  ame column..**.*
2a970 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  * ^If sqlite3_ma
2a980 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72  lloc() fails dur
2a990 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69  ing the processi
2a9a0 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75  ng of either rou
2a9b0 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61  tine.** (for exa
2a9c0 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f  mple during a co
2a9d0 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54  nversion from UT
2a9e0 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74  F-8 to UTF-16) t
2a9f0 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  hen a.** NULL po
2aa00 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
2aa10 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  d..**.** ^The na
2aa20 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63  me of a result c
2aa30 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c  olumn is the val
2aa40 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63  ue of the "AS" c
2aa50 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61  lause for.** tha
2aa60 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65  t column, if the
2aa70 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75  re is an AS clau
2aa80 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73  se.  If there is
2aa90 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a   no AS clause.**
2aaa0 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f   then the name o
2aab0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
2aac0 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20  unspecified and 
2aad0 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a  may change from.
2aae0 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f  ** one release o
2aaf0 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  f SQLite to the 
2ab00 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  next..*/.const c
2ab10 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2ab20 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  umn_name(sqlite3
2ab30 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
2ab40 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2ab50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
2ab60 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2ab70 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int N);../*.** 
2ab80 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65  CAPI3REF: Source
2ab90 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75   Of Data In A Qu
2aba0 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a  ery Result.**.**
2abb0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
2abc0 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73   provide a means
2abd0 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68   to determine th
2abe0 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  e database, tabl
2abf0 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20  e, and.** table 
2ac00 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74  column that is t
2ac10 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70  he origin of a p
2ac20 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74  articular result
2ac30 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53   column in.** [S
2ac40 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2ac50 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  ..** ^The name o
2ac60 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  f the database o
2ac70 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d  r table or colum
2ac80 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65  n can be returne
2ac90 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61  d as.** either a
2aca0 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
2acb0 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f   string.  ^The _
2acc0 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e  database_ routin
2acd0 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65  es return.** the
2ace0 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20   database name, 
2acf0 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74  the _table_ rout
2ad00 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
2ad10 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a  table name, and.
2ad20 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72  ** the origin_ r
2ad30 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
2ad40 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a  he column name..
2ad50 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
2ad60 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64   string is valid
2ad70 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70   until the [prep
2ad80 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2ad90 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20  is destroyed.** 
2ada0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
2adb0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
2adc0 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e  til the statemen
2add0 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  t is automatical
2ade0 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64  ly.** reprepared
2adf0 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61   by the first ca
2ae00 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2ae10 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72  tep()] for a par
2ae20 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f  ticular run.** o
2ae30 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65  r until the same
2ae40 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
2ae50 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61  requested.** aga
2ae60 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e  in in a differen
2ae70 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a  t encoding..**.*
2ae80 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74  * ^The names ret
2ae90 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72  urned are the or
2aea0 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65  iginal un-aliase
2aeb0 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a  d names of the.*
2aec0 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  * database, tabl
2aed0 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a  e, and column..*
2aee0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
2aef0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73  argument to thes
2af00 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20  e interfaces is 
2af10 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2af20 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73  ement]..** ^Thes
2af30 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
2af40 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
2af50 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73  bout the Nth res
2af60 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  ult column retur
2af70 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74  ned by.** the st
2af80 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e  atement, where N
2af90 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   is the second f
2afa0 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
2afb0 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d  ..** ^The left-m
2afc0 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f  ost column is co
2afd0 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65  lumn 0 for these
2afe0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
2aff0 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
2b000 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  umn returned by 
2b010 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2b020 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f   an expression o
2b030 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e  r.** subquery an
2b040 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d  d is not a colum
2b050 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c  n value, then al
2b060 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  l of these funct
2b070 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e  ions return.** N
2b080 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ULL.  ^These rou
2b090 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  tine might also 
2b0a0 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61  return NULL if a
2b0b0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
2b0c0 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75  on error.** occu
2b0d0 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c  rs.  ^Otherwise,
2b0e0 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65   they return the
2b0f0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74   name of the att
2b100 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20  ached database, 
2b110 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c  table,.** or col
2b120 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72  umn that query r
2b130 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73  esult column was
2b140 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e   extracted from.
2b150 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20  .**.** ^As with 
2b160 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65  all other SQLite
2b170 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f   APIs, those who
2b180 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74  se names end wit
2b190 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a  h "16" return.**
2b1a0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
2b1b0 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20  strings and the 
2b1c0 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20  other functions 
2b1d0 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a  return UTF-8..**
2b1e0 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20  .** ^These APIs 
2b1f0 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62  are only availab
2b200 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
2b210 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
2b220 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
2b230 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
2b240 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65  _METADATA] C-pre
2b250 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
2b260 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
2b270 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
2b280 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  all one or more 
2b290 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2b2a0 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61  s against the sa
2b2b0 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  me.** prepared s
2b2c0 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c  tatement and col
2b2d0 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20  umn at the same 
2b2e0 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
2b2f0 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64  sults are.** und
2b300 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  efined..**.** If
2b310 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
2b320 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
2b330 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   more.** [sqlite
2b340 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
2b350 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20  e_name | column 
2b360 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61  metadata interfa
2b370 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ces].** for the 
2b380 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
2b390 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65  tatement] and re
2b3a0 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  sult column.** a
2b3b0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
2b3c0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
2b3d0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
2b3e0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
2b3f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
2b400 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69  tabase_name(sqli
2b410 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2b420 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2b430 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
2b440 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ase_name16(sqlit
2b450 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
2b460 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2b470 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
2b480 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
2b490 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
2b4a0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2b4b0 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36  umn_table_name16
2b4c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2b4d0 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
2b4e0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2b4f0 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69  origin_name(sqli
2b500 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2b510 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2b520 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
2b530 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
2b540 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
2b550 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2b560 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
2b570 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
2b580 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  t.**.** ^(The fi
2b590 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
2b5a0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2b5b0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74  tement]..** If t
2b5c0 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73  his statement is
2b5d0 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
2b5e0 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74  ement and the Nt
2b5f0 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a  h column of the.
2b600 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75  ** returned resu
2b610 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b  lt set of that [
2b620 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62  SELECT] is a tab
2b630 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61  le column (not a
2b640 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
2b650 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65  or subquery) the
2b660 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  n the declared t
2b670 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
2b680 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65  .** column is re
2b690 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74  turned.)^  ^If t
2b6a0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
2b6b0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2b6c0 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  is an.** express
2b6d0 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c  ion or subquery,
2b6e0 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   then a NULL poi
2b6f0 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
2b700 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
2b710 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
2b720 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
2b730 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65  d..**.** ^(For e
2b740 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68  xample, given th
2b750 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
2b760 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20  a:.**.** CREATE 
2b770 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49  TABLE t1(c1 VARI
2b780 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20  ANT);.**.** and 
2b790 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
2b7a0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
2b7b0 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45  mpiled:.**.** SE
2b7c0 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20  LECT c1 + 1, c1 
2b7d0 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74  FROM t1;.**.** t
2b7e0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c  his routine woul
2b7f0 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72  d return the str
2b800 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f  ing "VARIANT" fo
2b810 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73  r the second res
2b820 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69  ult.** column (i
2b830 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c  ==1), and a NULL
2b840 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
2b850 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f   first result co
2b860 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a  lumn (i==0).)^.*
2b870 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
2b880 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69  s dynamic run-ti
2b890 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20  me typing.  ^So 
2b8a0 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63  just because a c
2b8b0 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c  olumn.** is decl
2b8c0 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  ared to contain 
2b8d0 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70  a particular typ
2b8e0 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20  e does not mean 
2b8f0 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61  that the.** data
2b900 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20   stored in that 
2b910 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65  column is of the
2b920 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20   declared type. 
2b930 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74   SQLite is.** st
2b940 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75  rongly typed, bu
2b950 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20  t the typing is 
2b960 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74  dynamic not stat
2b970 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73  ic.  ^Type.** is
2b980 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2b990 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75   individual valu
2b9a0 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65  es, not with the
2b9b0 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75   containers.** u
2b9c0 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73  sed to hold thos
2b9d0 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e  e values..*/.con
2b9e0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2b9f0 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
2ba00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2ba10 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
2ba20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2ba30 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74  decltype16(sqlit
2ba40 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
2ba50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2ba60 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20  Evaluate An SQL 
2ba70 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
2ba80 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65  After a [prepare
2ba90 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73  d statement] has
2baa0 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75   been prepared u
2bab0 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b  sing either.** [
2bac0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2bad0 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
2bae0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2baf0 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20  ] or one of the 
2bb00 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
2bb10 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  aces [sqlite3_pr
2bb20 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c  epare()] or [sql
2bb30 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2bb40 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ], this function
2bb50 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  .** must be call
2bb60 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  ed one or more t
2bb70 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65  imes to evaluate
2bb80 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a   the statement..
2bb90 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c  **.** The detail
2bba0 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f  s of the behavio
2bbb0 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  r of the sqlite3
2bbc0 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63  _step() interfac
2bbd0 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77  e depend.** on w
2bbe0 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65  hether the state
2bbf0 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65  ment was prepare
2bc00 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65  d using the newe
2bc10 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  r "v2" interface
2bc20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2bc30 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
2bc40 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2bc50 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f  6_v2()] or the o
2bc60 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69  lder legacy.** i
2bc70 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65  nterface [sqlite
2bc80 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
2bc90 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2bca0 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65  e16()].  The use
2bcb0 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22   of the.** new "
2bcc0 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
2bcd0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
2bce0 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
2bcf0 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79  s but the legacy
2bd00 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69  .** interface wi
2bd10 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  ll continue to b
2bd20 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a  e supported..**.
2bd30 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63  ** ^In the legac
2bd40 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
2bd50 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69   return value wi
2bd60 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51  ll be either [SQ
2bd70 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b  LITE_BUSY],.** [
2bd80 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53  SQLITE_DONE], [S
2bd90 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c  QLITE_ROW], [SQL
2bda0 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b  ITE_ERROR], or [
2bdb0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a  SQLITE_MISUSE]..
2bdc0 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76 32  ** ^With the "v2
2bdd0 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79  " interface, any
2bde0 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72   of the other [r
2bdf0 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a  esult codes] or.
2be00 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
2be10 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74  ult codes] might
2be20 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 20   be returned as 
2be30 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  well..**.** ^[SQ
2be40 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73  LITE_BUSY] means
2be50 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
2be60 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e  se engine was un
2be70 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20  able to acquire 
2be80 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
2be90 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74  locks it needs t
2bea0 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e  o do its job.  ^
2beb0 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
2bec0 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a   is a [COMMIT].*
2bed0 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73  * or occurs outs
2bee0 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63  ide of an explic
2bef0 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
2bf00 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74  then you can ret
2bf10 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  ry the.** statem
2bf20 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61  ent.  If the sta
2bf30 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20  tement is not a 
2bf40 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63  [COMMIT] and occ
2bf50 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a  urs within an.**
2bf60 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
2bf70 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73  ction then you s
2bf80 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74  hould rollback t
2bf90 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62  he transaction b
2bfa0 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75  efore.** continu
2bfb0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ing..**.** ^[SQL
2bfc0 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20  ITE_DONE] means 
2bfd0 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65  that the stateme
2bfe0 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  nt has finished 
2bff0 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63  executing.** suc
2c000 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69  cessfully.  sqli
2c010 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
2c020 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
2c030 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69  again on this vi
2c040 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
2c050 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63   without first c
2c060 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2c070 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65  reset()] to rese
2c080 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a  t the virtual.**
2c090 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f   machine back to
2c0a0 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
2c0b0 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  te..**.** ^If th
2c0c0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
2c0d0 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72  being executed r
2c0e0 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c  eturns any data,
2c0f0 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   then [SQLITE_RO
2c100 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  W].** is returne
2c110 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65  d each time a ne
2c120 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73  w row of data is
2c130 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65   ready for proce
2c140 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20  ssing by the.** 
2c150 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75  caller. The valu
2c160 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73  es may be access
2c170 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f  ed using the [co
2c180 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
2c190 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74  tions]..** sqlit
2c1a0 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c  e3_step() is cal
2c1b0 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74  led again to ret
2c1c0 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72  rieve the next r
2c1d0 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a  ow of data..**.*
2c1e0 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  * ^[SQLITE_ERROR
2c1f0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72  ] means that a r
2c200 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73  un-time error (s
2c210 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61  uch as a constra
2c220 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e  int.** violation
2c230 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20  ) has occurred. 
2c240 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2c250 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
2c260 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a  lled again on.**
2c270 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e   the VM. More in
2c280 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65  formation may be
2c290 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e   found by callin
2c2a0 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  g [sqlite3_errms
2c2b0 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  g()]..** ^With t
2c2c0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
2c2d0 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63  ace, a more spec
2c2e0 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
2c2f0 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (for example,.**
2c300 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
2c310 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48  PT], [SQLITE_SCH
2c320 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f  EMA], [SQLITE_CO
2c330 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66  RRUPT], and so f
2c340 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20  orth).** can be 
2c350 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c  obtained by call
2c360 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
2c370 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20  et()] on the.** 
2c380 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2c390 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22  ent].  ^In the "
2c3a0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a  v2" interface,.*
2c3b0 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  * the more speci
2c3c0 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69  fic error code i
2c3d0 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  s returned direc
2c3e0 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73  tly by sqlite3_s
2c3f0 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51  tep()..**.** [SQ
2c400 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61  LITE_MISUSE] mea
2c410 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73  ns that the this
2c420 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c   routine was cal
2c430 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74  led inappropriat
2c440 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20  ely..** Perhaps 
2c450 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e  it was called on
2c460 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2c470 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
2c480 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e  .** already been
2c490 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2c4a0 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20  ze | finalized] 
2c4b0 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68  or on one that h
2c4c0 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ad.** previously
2c4d0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
2c4e0 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c  E_ERROR] or [SQL
2c4f0 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69  ITE_DONE].  Or i
2c500 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68  t could.** be th
2c510 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20  e case that the 
2c520 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
2c530 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  nnection is bein
2c540 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72  g used by two or
2c550 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73  .** more threads
2c560 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d   at the same mom
2c570 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a  ent in time..**.
2c580 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69  ** For all versi
2c590 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70  ons of SQLite up
2c5a0 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e   to and includin
2c5b0 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61  g 3.6.23.1, a ca
2c5c0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
2c5d0 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20 72  3_reset()] was r
2c5e0 65 71 75 69 72 65 64 20 61 66 74 65 72 20 73 71  equired after sq
2c5f0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65 74  lite3_step() ret
2c600 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a  urned anything.*
2c610 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  * other than [SQ
2c620 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65  LITE_ROW] before
2c630 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
2c640 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a  invocation of.**
2c650 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
2c660 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73    Failure to res
2c670 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20  et the prepared 
2c680 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
2c690 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2c6a0 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75  et()] would resu
2c6b0 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45  lt in an [SQLITE
2c6c0 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20  _MISUSE] return 
2c6d0 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  from.** sqlite3_
2c6e0 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66 74  step().  But aft
2c6f0 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32  er version 3.6.2
2c700 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65  3.1, sqlite3_ste
2c710 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c  p() began.** cal
2c720 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
2c730 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63  set()] automatic
2c740 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72  ally in this cir
2c750 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72  cumstance rather
2c760 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69  .** than returni
2c770 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ng [SQLITE_MISUS
2c780 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74  E].  This is not
2c790 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f   considered a co
2c7a0 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62  mpatibility.** b
2c7b0 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79  reak because any
2c7c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61   application tha
2c7d0 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73 20  t ever receives 
2c7e0 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  an SQLITE_MISUSE
2c7f0 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f   error.** is bro
2c800 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f  ken by definitio
2c810 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  n.  The [SQLITE_
2c820 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20  OMIT_AUTORESET] 
2c830 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
2c840 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ion.** can be us
2c850 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68  ed to restore th
2c860 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
2c870 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66  r..**.** <b>Goof
2c880 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72  y Interface Aler
2c890 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65  t:</b> In the le
2c8a0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
2c8b0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
2c8c0 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73  ().** API always
2c8d0 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72   returns a gener
2c8e0 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b  ic error code, [
2c8f0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66  SQLITE_ERROR], f
2c900 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20  ollowing any.** 
2c910 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e  error other than
2c920 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61   [SQLITE_BUSY] a
2c930 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  nd [SQLITE_MISUS
2c940 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61  E].  You must ca
2c950 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  ll.** [sqlite3_r
2c960 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
2c970 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2c980 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
2c990 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73   one of the.** s
2c9a0 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
2c9b0 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65  odes] that bette
2c9c0 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  r describes the 
2c9d0 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d  error..** We adm
2c9e0 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20  it that this is 
2c9f0 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20  a goofy design. 
2ca00 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73   The problem has
2ca10 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77   been fixed.** w
2ca20 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
2ca30 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20  erface.  If you 
2ca40 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79  prepare all of y
2ca50 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  our SQL statemen
2ca60 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68  ts.** using eith
2ca70 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
2ca80 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
2ca90 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2caa0 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a  v2()] instead.**
2cab0 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b   of the legacy [
2cac0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2cad0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2cae0 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74  prepare16()] int
2caf0 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e  erfaces,.** then
2cb00 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66   the more specif
2cb10 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
2cb20 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69   are returned di
2cb30 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c  rectly.** by sql
2cb40 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68  ite3_step().  Th
2cb50 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32  e use of the "v2
2cb60 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
2cb70 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69  ecommended..*/.i
2cb80 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  nt sqlite3_step(
2cb90 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2cba0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2cbb0 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   Number of colum
2cbc0 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73  ns in a result s
2cbd0 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  et.**.** ^The sq
2cbe0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2cbf0 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (P) interface re
2cc00 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2cc10 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
2cc20 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f  he.** current ro
2cc30 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
2cc40 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64  set of [prepared
2cc50 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a   statement] P..*
2cc60 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 73  * ^If prepared s
2cc70 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20  tatement P does 
2cc80 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 73  not have results
2cc90 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e   ready to return
2cca0 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74  .** (via calls t
2ccb0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
2ccc0 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69  olumn_int | sqli
2ccd0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20  te3_column_*()] 
2cce0 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  of.** interfaces
2ccf0 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64  ) then sqlite3_d
2cd00 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74  ata_count(P) ret
2cd10 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20  urns 0..** ^The 
2cd20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2cd30 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c  nt(P) routine al
2cd40 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  so returns 0 if 
2cd50 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  P is a NULL poin
2cd60 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ter..** ^The sql
2cd70 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2cd80 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  P) routine retur
2cd90 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65 76  ns 0 if the prev
2cda0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  ious call to.** 
2cdb0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50  [sqlite3_step](P
2cdc0 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  ) returned [SQLI
2cdd0 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20  TE_DONE].  ^The 
2cde0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2cdf0 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65  nt(P).** will re
2ce00 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66  turn non-zero if
2ce10 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
2ce20 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d  o [sqlite3_step]
2ce30 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  (P) returned.** 
2ce40 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78  [SQLITE_ROW], ex
2ce50 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73 65  cept in the case
2ce60 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20   of the [PRAGMA 
2ce70 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75  incremental_vacu
2ce80 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20  um].** where it 
2ce90 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a  always returns z
2cea0 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73  ero since each s
2ceb0 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74  tep of that mult
2cec0 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61  i-step.** pragma
2ced0 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d   returns 0 colum
2cee0 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a  ns of data..**.*
2cef0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2cf00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
2cf10 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  t()].*/.int sqli
2cf20 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73  te3_data_count(s
2cf30 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2cf40 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2cf50 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61  3REF: Fundamenta
2cf60 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b  l Datatypes.** K
2cf70 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f  EYWORDS: SQLITE_
2cf80 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65  TEXT.**.** ^(Eve
2cf90 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69  ry value in SQLi
2cfa0 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69  te has one of fi
2cfb0 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64  ve fundamental d
2cfc0 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20  atatypes:.**.** 
2cfd0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  <ul>.** <li> 64-
2cfe0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
2cff0 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  er.** <li> 64-bi
2d000 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20  t IEEE floating 
2d010 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20  point number.** 
2d020 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c  <li> string.** <
2d030 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e  li> BLOB.** <li>
2d040 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e   NULL.** </ul>)^
2d050 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
2d060 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73  stants are codes
2d070 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f   for each of tho
2d080 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20  se types..**.** 
2d090 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51  Note that the SQ
2d0a0 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61  LITE_TEXT consta
2d0b0 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64  nt was also used
2d0c0 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   in SQLite versi
2d0d0 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f  on 2.** for a co
2d0e0 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65  mpletely differe
2d0f0 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66  nt meaning.  Sof
2d100 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73  tware that links
2d110 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a   against both.**
2d120 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2d130 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72  2 and SQLite ver
2d140 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73  sion 3 should us
2d150 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20  e SQLITE3_TEXT, 
2d160 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45  not.** SQLITE_TE
2d170 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  XT..*/.#define S
2d180 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31  QLITE_INTEGER  1
2d190 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2d1a0 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69  FLOAT    2.#defi
2d1b0 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20  ne SQLITE_BLOB  
2d1c0 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
2d1d0 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23  ITE_NULL     5.#
2d1e0 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  ifdef SQLITE_TEX
2d1f0 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45  T.# undef SQLITE
2d200 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65  _TEXT.#else.# de
2d210 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54  fine SQLITE_TEXT
2d220 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64       3.#endif.#d
2d230 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45  efine SQLITE3_TE
2d240 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20  XT     3../*.** 
2d250 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
2d260 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51   Values From A Q
2d270 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  uery.** KEYWORDS
2d280 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  : {column access
2d290 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a   functions}.**.*
2d2a0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2d2b0 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c   form the "resul
2d2c0 74 20 73 65 74 22 20 69 6e 74 65 72 66 61 63 65  t set" interface
2d2d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
2d2e0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69  outines return i
2d2f0 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
2d300 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e   a single column
2d310 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a   of the current.
2d320 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66  ** result row of
2d330 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65   a query.  ^In e
2d340 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69  very case the fi
2d350 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
2d360 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
2d370 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2d380 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73  atement] that is
2d390 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64   being evaluated
2d3a0 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
2d3b0 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61  tmt*].** that wa
2d3c0 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  s returned from 
2d3d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2d3e0 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
2d3f0 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a   its variants).*
2d400 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  * and the second
2d410 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
2d420 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f   index of the co
2d430 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69  lumn for which i
2d440 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68  nformation.** sh
2d450 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
2d460 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  . ^The leftmost 
2d470 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
2d480 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65  sult set has the
2d490 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68   index 0..** ^Th
2d4a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
2d4b0 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
2d4c0 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  t can be determi
2d4d0 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ned using.** [sq
2d4e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
2d4f0 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  nt()]..**.** If 
2d500 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
2d510 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65  t does not curre
2d520 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20  ntly point to a 
2d530 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66  valid row, or if
2d540 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69   the.** column i
2d550 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
2d560 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74  ange, the result
2d570 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2d580 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2d590 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c   may only be cal
2d5a0 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73  led when the mos
2d5b0 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
2d5c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
2d5d0 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
2d5e0 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61  d [SQLITE_ROW] a
2d5f0 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73  nd neither.** [s
2d600 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2d610 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  nor [sqlite3_fin
2d620 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65  alize()] have be
2d630 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71  en called subseq
2d640 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e  uently..** If an
2d650 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
2d660 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61  nes are called a
2d670 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  fter [sqlite3_re
2d680 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
2d690 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2d6a0 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69  ] or after [sqli
2d6b0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
2d6c0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65  returned.** some
2d6d0 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
2d6e0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74   [SQLITE_ROW], t
2d6f0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
2d700 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
2d710 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2d720 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
2d730 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
2d740 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a  3_finalize()].**
2d750 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
2d760 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72   a different thr
2d770 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66  ead while any of
2d780 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
2d790 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20  ** are pending, 
2d7a0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
2d7b0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
2d7c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2d7d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2d7e0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2d7f0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
2d800 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
2d810 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  pe code] for the
2d820 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79   initial data ty
2d830 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73  pe.** of the res
2d840 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68  ult column.  ^Th
2d850 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65  e returned value
2d860 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
2d870 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20  TE_INTEGER],.** 
2d880 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20  [SQLITE_FLOAT], 
2d890 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b  [SQLITE_TEXT], [
2d8a0 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72  SQLITE_BLOB], or
2d8b0 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20   [SQLITE_NULL]. 
2d8c0 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   The value.** re
2d8d0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2d8e0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
2d8f0 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66  is only meaningf
2d900 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a  ul if no type.**
2d910 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76   conversions hav
2d920 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65  e occurred as de
2d930 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20  scribed below.  
2d940 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e  After a type con
2d950 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20  version,.** the 
2d960 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
2d970 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2d980 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66  _type() is undef
2d990 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a  ined.  Future.**
2d9a0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
2d9b0 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74  ite may change t
2d9c0 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73  he behavior of s
2d9d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2d9e0 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  pe().** followin
2d9f0 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  g a type convers
2da00 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ion..**.** ^If t
2da10 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
2da20 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72  LOB or UTF-8 str
2da30 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
2da40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2da50 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  s().** routine r
2da60 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2da70 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2da80 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
2da90 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
2daa0 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36  sult is a UTF-16
2dab0 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
2dac0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2dad0 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  es() converts.**
2dae0 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
2daf0 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65  TF-8 and then re
2db00 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2db10 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
2db20 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2db30 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
2db40 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2db50 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73  umn_bytes() uses
2db60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
2db70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
2db80 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
2db90 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  o a UTF-8 string
2dba0 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
2dbb0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2dbc0 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
2dbd0 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
2dbe0 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
2dbf0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2dc00 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72  mn_bytes() retur
2dc10 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
2dc20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2dc30 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31   a BLOB or UTF-1
2dc40 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  6 string then th
2dc50 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2dc60 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f  _bytes16().** ro
2dc70 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
2dc80 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2dc90 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
2dca0 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
2dcb0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2dcc0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74   UTF-8 string, t
2dcd0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2dce0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e  mn_bytes16() con
2dcf0 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
2dd00 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e  ing to UTF-16 an
2dd10 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
2dd20 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2dd30 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  es..** ^If the r
2dd40 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
2dd50 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
2dd60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2dd70 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b  es16() uses.** [
2dd80 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
2dd90 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
2dda0 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
2ddb0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64  TF-16 string and
2ddc0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
2ddd0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2dde0 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
2ddf0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2de00 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
2de10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2de20 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73  ytes16() returns
2de30 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   zero..**.** ^Th
2de40 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
2de50 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
2de60 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e  lumn_bytes()] an
2de70 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  d .** [sqlite3_c
2de80 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d  olumn_bytes16()]
2de90 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20   do not include 
2dea0 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
2deb0 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a  tors at the end.
2dec0 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  ** of the string
2ded0 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a  .  ^For clarity:
2dee0 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75   the values retu
2def0 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
2df00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2df10 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2df20 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2df30 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65  )] are the numbe
2df40 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e  r of.** bytes in
2df50 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74   the string, not
2df60 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
2df70 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
2df80 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e   ^Strings return
2df90 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2dfa0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20  lumn_text() and 
2dfb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2dfc0 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e  ext16(),.** even
2dfd0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20   empty strings, 
2dfe0 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d  are always zero-
2dff0 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
2e000 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  e return.** valu
2e010 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
2e020 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72  olumn_blob() for
2e030 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
2e040 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  LOB is a NULL po
2e050 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
2e060 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
2e070 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
2e080 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
2e090 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
2e0a0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2e0b0 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75  e] object.  An u
2e0c0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2e0d0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a  e3_value object.
2e0e0 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ** may only be u
2e0f0 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  sed with [sqlite
2e100 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20  3_bind_value()] 
2e110 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  and [sqlite3_res
2e120 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ult_value()]..**
2e130 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65   If the [unprote
2e140 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2e150 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  ue] object retur
2e160 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
2e170 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
2e180 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e  )] is used in an
2e190 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63  y other way, inc
2e1a0 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20  luding calls.** 
2e1b0 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65  to routines like
2e1c0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2e1d0 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  int()], [sqlite3
2e1e0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
2e1f0 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
2e200 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74  alue_bytes()], t
2e210 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
2e220 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2e230 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2e240 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63  nes attempt to c
2e250 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
2e260 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61   where appropria
2e270 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61  te.  ^For.** exa
2e280 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74  mple, if the int
2e290 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
2e2a0 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e  tion is FLOAT an
2e2b0 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a  d a text result.
2e2c0 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c  ** is requested,
2e2d0 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
2e2e0 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  tf()] is used in
2e2f0 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66  ternally to perf
2e300 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65  orm the.** conve
2e310 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61  rsion automatica
2e320 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c  lly.  ^(The foll
2e330 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61  owing table deta
2e340 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69  ils the conversi
2e350 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  ons.** that are 
2e360 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c  applied:.**.** <
2e370 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c  blockquote>.** <
2e380 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
2e390 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e  >.** <tr><th> In
2e3a0 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c  ternal<br>Type <
2e3b0 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72  th> Requested<br
2e3c0 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76  >Type <th>  Conv
2e3d0 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72  ersion.**.** <tr
2e3e0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
2e3f0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
2e400 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a  d> Result is 0.*
2e410 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2e420 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
2e430 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2e440 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64  s 0.0.** <tr><td
2e450 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
2e460 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52    TEXT    <td> R
2e470 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20  esult is a NULL 
2e480 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
2e490 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
2e4a0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
2e4b0 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c   Result is a NUL
2e4c0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
2e4d0 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
2e4e0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
2e4f0 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
2e500 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74  integer to float
2e510 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
2e520 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58  EGER  <td>   TEX
2e530 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
2e540 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
2e550 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
2e560 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
2e570 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
2e580 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45  > Same as INTEGE
2e590 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  R->TEXT.** <tr><
2e5a0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
2e5b0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
2e5c0 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47   [CAST] to INTEG
2e5d0 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ER.** <tr><td>  
2e5e0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54  FLOAT   <td>   T
2e5f0 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
2e600 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
2e610 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  he float.** <tr>
2e620 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
2e630 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
2e640 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42  > [CAST] to BLOB
2e650 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
2e660 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  XT    <td> INTEG
2e670 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  ER   <td> [CAST]
2e680 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c   to INTEGER.** <
2e690 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
2e6a0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
2e6b0 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52  <td> [CAST] to R
2e6c0 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EAL.** <tr><td> 
2e6d0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20   TEXT    <td>   
2e6e0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20  BLOB    <td> No 
2e6f0 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74  change.** <tr><t
2e700 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
2e710 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
2e720 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45  [CAST] to INTEGE
2e730 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  R.** <tr><td>  B
2e740 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  LOB    <td>  FLO
2e750 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  AT    <td> [CAST
2e760 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72  ] to REAL.** <tr
2e770 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
2e780 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
2e790 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65  d> Add a zero te
2e7a0 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64  rminator if need
2e7b0 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  ed.** </table>.*
2e7c0 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  * </blockquote>)
2e7d0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ^.**.** The tabl
2e7e0 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65  e above makes re
2e7f0 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64  ference to stand
2e800 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75  ard C library fu
2e810 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a  nctions atoi().*
2e820 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53  * and atof().  S
2e830 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72  QLite does not r
2e840 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20  eally use these 
2e850 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68  functions.  It h
2e860 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71  as its.** own eq
2e870 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61  uivalent interna
2e880 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65  l routines.  The
2e890 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66   atoi() and atof
2e8a0 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  () names are.** 
2e8b0 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c  used in the tabl
2e8c0 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e  e for brevity an
2e8d0 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61  d because they a
2e8e0 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d  re familiar to m
2e8f0 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d  ost.** C program
2e900 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  mers..**.** Note
2e910 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20   that when type 
2e920 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75  conversions occu
2e930 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  r, pointers retu
2e940 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a  rned by prior.**
2e950 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
2e960 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
2e970 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e980 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a  text(), and/or.*
2e990 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
2e9a0 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65  _text16() may be
2e9b0 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
2e9c0 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   Type conversion
2e9d0 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e  s and pointer in
2e9e0 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68  validations migh
2e9f0 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  t occur.** in th
2ea00 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65  e following case
2ea10 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
2ea20 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
2ea30 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42  l content is a B
2ea40 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  LOB and sqlite3_
2ea50 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
2ea60 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
2ea70 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2ea80 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a   is called.  A z
2ea90 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d  ero-terminator m
2eaa0 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65  ight.**      nee
2eab0 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f  d to be added to
2eac0 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69   the string.</li
2ead0 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
2eae0 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
2eaf0 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20   UTF-8 text and 
2eb00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2eb10 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20  ytes16() or.**  
2eb20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
2eb30 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
2eb40 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
2eb50 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
2eb60 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
2eb70 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a   UTF-16.</li>.**
2eb80 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
2eb90 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
2eba0 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c  -16 text and sql
2ebb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2ebc0 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  s() or.**      s
2ebd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2ebe0 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  xt() is called. 
2ebf0 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
2ec00 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
2ec10 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e  *      to UTF-8.
2ec20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
2ec30 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e  *.** ^Conversion
2ec40 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36  s between UTF-16
2ec50 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20  be and UTF-16le 
2ec60 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20  are always done 
2ec70 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a  in place and do.
2ec80 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74  ** not invalidat
2ec90 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  e a prior pointe
2eca0 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75  r, though of cou
2ecb0 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  rse the content 
2ecc0 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a  of the buffer.**
2ecd0 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20   that the prior 
2ece0 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63  pointer referenc
2ecf0 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65  es will have bee
2ed00 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68  n modified.  Oth
2ed10 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63  er kinds.** of c
2ed20 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f  onversion are do
2ed30 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e  ne in place when
2ed40 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c   it is possible,
2ed50 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74   but sometimes t
2ed60 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70  hey.** are not p
2ed70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74  ossible and in t
2ed80 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72  hose cases prior
2ed90 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e   pointers are in
2eda0 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  validated..**.**
2edb0 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20   The safest and 
2edc0 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d  easiest to remem
2edd0 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f  ber policy is to
2ede0 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f   invoke these ro
2edf0 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65  utines.** in one
2ee00 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
2ee10 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  g ways:.**.** <u
2ee20 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  l>.**  <li>sqlit
2ee30 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2ee40 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
2ee50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2ee60 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
2ee70 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
2ee80 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20  blob() followed 
2ee90 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2eea0 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
2eeb0 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
2eec0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
2eed0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
2eee0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2eef0 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  6()</li>.** </ul
2ef00 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  >.**.** In other
2ef10 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75   words, you shou
2ef20 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  ld call sqlite3_
2ef30 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a  column_text(),.*
2ef40 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
2ef50 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69  _blob(), or sqli
2ef60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2ef70 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72  6() first to for
2ef80 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a  ce the result.**
2ef90 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65   into the desire
2efa0 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69  d format, then i
2efb0 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f  nvoke sqlite3_co
2efc0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
2efd0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
2efe0 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66  n_bytes16() to f
2eff0 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ind the size of 
2f000 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20  the result.  Do 
2f010 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a  not mix calls.**
2f020 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
2f030 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  mn_text() or sql
2f040 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2f050 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  () with calls to
2f060 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2f070 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e  mn_bytes16(), an
2f080 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c  d do not mix cal
2f090 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
2f0a0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a  lumn_text16().**
2f0b0 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73   with calls to s
2f0c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2f0d0 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tes()..**.** ^Th
2f0e0 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
2f0f0 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e  ned are valid un
2f100 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65  til a type conve
2f110 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a  rsion occurs as.
2f120 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f  ** described abo
2f130 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71  ve, or until [sq
2f140 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
2f150 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2f160 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
2f170 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73  3_finalize()] is
2f180 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d   called.  ^The m
2f190 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64  emory space used
2f1a0 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73   to hold strings
2f1b0 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73  .** and BLOBs is
2f1c0 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63   freed automatic
2f1d0 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74  ally.  Do <b>not
2f1e0 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f  </b> pass the po
2f1f0 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a  inters returned.
2f200 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
2f210 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c  _column_blob()],
2f220 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2f230 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69  _text()], etc. i
2f240 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nto.** [sqlite3_
2f250 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  free()]..**.** ^
2f260 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  (If a memory all
2f270 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
2f280 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20  curs during the 
2f290 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e  evaluation of an
2f2a0 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f  y.** of these ro
2f2b0 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c  utines, a defaul
2f2c0 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  t value is retur
2f2d0 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ned.  The defaul
2f2e0 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69  t value.** is ei
2f2f0 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72  ther the integer
2f300 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67   0, the floating
2f310 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e   point number 0.
2f320 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20  0, or a NULL.** 
2f330 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71  pointer.  Subseq
2f340 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
2f350 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
2f360 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ] will return.**
2f370 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
2f380 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64  )^.*/.const void
2f390 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2f3a0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
2f3b0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2f3c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2f3d0 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  mn_bytes(sqlite3
2f3e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2f3f0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2f400 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71  olumn_bytes16(sq
2f410 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2f420 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73   iCol);.double s
2f430 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
2f440 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
2f450 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
2f460 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2f470 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  n_int(sqlite3_st
2f480 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2f490 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
2f4a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
2f4b0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
2f4c0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
2f4d0 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
2f4e0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2f4f0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
2f500 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2f510 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2f520 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2f530 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2f540 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
2f550 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2f560 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
2f570 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
2f580 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c  lite3_value *sql
2f590 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2f5a0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2f5b0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a   int iCol);../*.
2f5c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73  ** CAPI3REF: Des
2f5d0 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20  troy A Prepared 
2f5e0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
2f5f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2f600 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66  te3_finalize() f
2f610 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
2f620 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70  d to delete a [p
2f630 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f640 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  t]..** ^If the m
2f650 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
2f660 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61  ation of the sta
2f670 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72  tement encounter
2f680 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20  ed no errors.** 
2f690 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d  or if the statem
2f6a0 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65  ent is never bee
2f6b0 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65  n evaluated, the
2f6c0 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  n sqlite3_finali
2f6d0 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  ze() returns.** 
2f6e0 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20  SQLITE_OK.  ^If 
2f6f0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2f700 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74  evaluation of st
2f710 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64  atement S failed
2f720 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
2f730 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65  3_finalize(S) re
2f740 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70  turns the approp
2f750 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
2f760 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  e] or.** [extend
2f770 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  ed error code]..
2f780 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2f790 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72  e3_finalize(S) r
2f7a0 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61  outine can be ca
2f7b0 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e  lled at any poin
2f7c0 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20  t during.** the 
2f7d0 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70  life cycle of [p
2f7e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f7f0 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20  t] S:.** before 
2f800 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65  statement S is e
2f810 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61  ver evaluated, a
2f820 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d  fter.** one or m
2f830 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ore calls to [sq
2f840 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20  lite3_reset()], 
2f850 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c  or after any cal
2f860 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  l.** to [sqlite3
2f870 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c  _step()] regardl
2f880 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
2f890 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d  r not the statem
2f8a0 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c  ent has.** compl
2f8b0 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a  eted execution..
2f8c0 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20  **.** ^Invoking 
2f8d0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2f8e0 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69  () on a NULL poi
2f8f0 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65  nter is a harmle
2f900 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20  ss no-op..**.** 
2f910 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
2f920 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76  must finalize ev
2f930 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74  ery [prepared st
2f940 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65  atement] in orde
2f950 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65  r to avoid.** re
2f960 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49  source leaks.  I
2f970 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20  t is a grievous 
2f980 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70  error for the ap
2f990 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79  plication to try
2f9a0 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65   to use.** a pre
2f9b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2f9c0 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
2f9d0 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e  n finalized.  An
2f9e0 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61  y use of a prepa
2f9f0 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
2fa00 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
2fa10 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e  en finalized can
2fa20 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
2fa30 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65  ined and.** unde
2fa40 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72  sirable behavior
2fa50 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c   such as segfaul
2fa60 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72  ts and heap corr
2fa70 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73  uption..*/.int s
2fa80 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2fa90 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2faa0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2fab0 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50  I3REF: Reset A P
2fac0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2fad0 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
2fae0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  he sqlite3_reset
2faf0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
2fb00 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61  alled to reset a
2fb10 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2fb20 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  ment].** object 
2fb30 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
2fb40 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79  ial state, ready
2fb50 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74   to be re-execut
2fb60 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20  ed..** ^Any SQL 
2fb70 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62  statement variab
2fb80 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c  les that had val
2fb90 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65  ues bound to the
2fba0 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b  m using.** the [
2fbb0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2fbc0 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
2fbd0 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e  _*() API] retain
2fbe0 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a   their values..*
2fbf0 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63  * Use [sqlite3_c
2fc00 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d  lear_bindings()]
2fc10 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69   to reset the bi
2fc20 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ndings..**.** ^T
2fc30 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
2fc40 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
2fc50 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70  resets the [prep
2fc60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2fc70 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65  S.** back to the
2fc80 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74   beginning of it
2fc90 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a  s program..**.**
2fca0 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
2fcb0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
2fcc0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
2fcd0 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
2fce0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2fcf0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
2fd00 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54  E_ROW] or [SQLIT
2fd10 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69  E_DONE],.** or i
2fd20 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
2fd30 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65  S)] has never be
2fd40 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  fore been called
2fd50 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b   on S,.** then [
2fd60 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2fd70 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ] returns [SQLIT
2fd80 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  E_OK]..**.** ^If
2fd90 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2fda0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2fdb0 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
2fdc0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
2fdd0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64  statement] S ind
2fde0 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c  icated an error,
2fdf0 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65   then.** [sqlite
2fe00 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
2fe10 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61  rns an appropria
2fe20 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  te [error code].
2fe30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
2fe40 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
2fe50 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f  nterface does no
2fe60 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
2fe70 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73  ues.** of any [s
2fe80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2fe90 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68  |bindings] on th
2fea0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2feb0 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74  ement] S..*/.int
2fec0 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73   sqlite3_reset(s
2fed0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2fee0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2fef0 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20  3REF: Create Or 
2ff00 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e  Redefine SQL Fun
2ff10 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ctions.** KEYWOR
2ff20 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72  DS: {function cr
2ff30 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d  eation routines}
2ff40 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
2ff50 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2ff60 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d  ed SQL function}
2ff70 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
2ff80 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2ff90 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
2ffa0 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66  }.**.** ^These f
2ffb0 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63  unctions (collec
2ffc0 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  tively known as 
2ffd0 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  "function creati
2ffe0 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a  on routines").**
2fff0 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64   are used to add
30000 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
30010 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20  r aggregates or 
30020 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20  to redefine the 
30030 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65  behavior.** of e
30040 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63  xisting SQL func
30050 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
30060 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64  tes.  The only d
30070 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 65  ifferences betwe
30080 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74  en.** these rout
30090 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 78  ines are the tex
300a0 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63  t encoding expec
300b0 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73  ted for.** the s
300c0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
300d0 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  (the name of the
300e0 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20   function being 
300f0 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20  created).** and 
30100 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20  the presence or 
30110 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73  absence of a des
30120 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
30130 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c   for.** the appl
30140 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
30150 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
30160 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
30170 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73   is the [databas
30180 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
30190 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a   which the SQL.*
301a0 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f  * function is to
301b0 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20   be added.  ^If 
301c0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
301d0 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  ses more than on
301e0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
301f0 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70  nnection then ap
30200 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
30210 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
30220 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a  must be added.**
30230 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
30240 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70  e connection sep
30250 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  arately..**.** ^
30260 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
30270 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65  eter is the name
30280 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63   of the SQL func
30290 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74  tion to be creat
302a0 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e  ed or.** redefin
302b0 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68  ed.  ^The length
302c0 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20   of the name is 
302d0 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62  limited to 255 b
302e0 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a  ytes in a UTF-8.
302f0 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ** representatio
30300 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20  n, exclusive of 
30310 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
30320 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74  tor.  ^Note that
30330 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e   the name.** len
30340 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20  gth limit is in 
30350 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74  UTF-8 bytes, not
30360 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20   characters nor 
30370 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a  UTF-16 bytes.  .
30380 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20  ** ^Any attempt 
30390 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63  to create a func
303a0 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67  tion with a long
303b0 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20  er name.** will 
303c0 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54  result in [SQLIT
303d0 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20  E_MISUSE] being 
303e0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
303f0 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  ^The third param
30400 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69  eter (nArg).** i
30410 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
30420 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74  arguments that t
30430 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
30440 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
30450 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20  takes. ^If this 
30460 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c  parameter is -1,
30470 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75   then the SQL fu
30480 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
30490 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20  regate may take 
304a0 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  any number of ar
304b0 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20  guments between 
304c0 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a  0 and the limit.
304d0 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74  ** set by [sqlit
304e0 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54  e3_limit]([SQLIT
304f0 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
30500 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20  _ARG]).  If the 
30510 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
30520 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  er is less than 
30530 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68  -1 or greater th
30540 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20  an 127 then the 
30550 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75  behavior is.** u
30560 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
30570 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
30580 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c  meter, eTextRep,
30590 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a   specifies what.
305a0 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20  ** [SQLITE_UTF8 
305b0 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d  | text encoding]
305c0 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69   this SQL functi
305d0 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a  on prefers for.*
305e0 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73  * its parameters
305f0 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
30600 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20 74 68  on should set th
30610 69 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  is parameter to.
30620 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ** [SQLITE_UTF16
30630 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e 63 74  LE] if the funct
30640 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
30650 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b  on invokes .** [
30660 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
30670 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20  xt16le()] on an 
30680 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54  input, or [SQLIT
30690 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20 74 68  E_UTF16BE] if th
306a0 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
306b0 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c  ion invokes [sql
306c0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
306d0 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70  6be()] on an inp
306e0 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  ut, or.** [SQLIT
306f0 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73 71 6c  E_UTF16] if [sql
30700 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
30710 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 6f 72  6()] is used, or
30720 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a   [SQLITE_UTF8].*
30730 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20 5e 54  * otherwise.  ^T
30740 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63  he same SQL func
30750 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69  tion may be regi
30760 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20  stered multiple 
30770 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64  times using.** d
30780 69 66 66 65 72 65 6e 74 20 70 72 65 66 65 72 72  ifferent preferr
30790 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
307a0 73 2c 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  s, with differen
307b0 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
307c0 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e  s for.** each en
307d0 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e  coding..** ^When
307e0 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
307f0 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
30800 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61   same function a
30810 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51  re available, SQ
30820 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63  Lite.** will pic
30830 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69  k the one that i
30840 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73  nvolves the leas
30850 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61  t amount of data
30860 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
30870 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
30880 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f 70 74  arameter may opt
30890 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64 20  ionally be ORed 
308a0 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 54  with [SQLITE_DET
308b0 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74  ERMINISTIC].** t
308c0 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20 74 68  o signal that th
308d0 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  e function will 
308e0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68  always return th
308f0 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20 67 69  e same result gi
30900 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ven.** the same 
30910 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20 61 20  inputs within a 
30920 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
30930 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20  ment.  Most SQL 
30940 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a  functions are.**
30950 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20   deterministic. 
30960 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72   The built-in [r
30970 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e  andom()] SQL fun
30980 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d  ction is an exam
30990 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63  ple of a.** func
309a0 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74  tion that is not
309b0 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20   deterministic. 
309c0 20 54 68 65 20 53 51 4c 69 74 65 20 71 75 65 72   The SQLite quer
309d0 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c  y planner is abl
309e0 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20  e to.** perform 
309f0 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d  additional optim
30a00 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65  izations on dete
30a10 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63 74 69  rministic functi
30a20 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f  ons, so use.** o
30a30 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45  f the [SQLITE_DE
30a40 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61  TERMINISTIC] fla
30a50 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  g is recommended
30a60 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65 2e   where possible.
30a70 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66  .**.** ^(The fif
30a80 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
30a90 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69  an arbitrary poi
30aa0 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65  nter.  The imple
30ab0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
30ac0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  .** function can
30ad0 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20   gain access to 
30ae0 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69  this pointer usi
30af0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ng [sqlite3_user
30b00 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a  _data()].)^.**.*
30b10 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65  * ^The sixth, se
30b20 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68  venth and eighth
30b30 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75   parameters, xFu
30b40 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46  nc, xStep and xF
30b50 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69  inal, are.** poi
30b60 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75  nters to C-langu
30b70 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  age functions th
30b80 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
30b90 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
30ba0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e  .** aggregate. ^
30bb0 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e  A scalar SQL fun
30bc0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
30bd0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
30be0 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a   of the xFunc.**
30bf0 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20   callback only; 
30c00 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75  NULL pointers mu
30c10 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20  st be passed as 
30c20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46  the xStep and xF
30c30 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65  inal.** paramete
30c40 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74  rs. ^An aggregat
30c50 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  e SQL function r
30c60 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
30c70 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74  mentation of xSt
30c80 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c  ep.** and xFinal
30c90 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65   and NULL pointe
30ca0 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  r must be passed
30cb0 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20   for xFunc. ^To 
30cc0 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69  delete an existi
30cd0 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  ng.** SQL functi
30ce0 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c  on or aggregate,
30cf0 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74   pass NULL point
30d00 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65  ers for all thre
30d10 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61  e function.** ca
30d20 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e  llbacks..**.** ^
30d30 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61  (If the ninth pa
30d40 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
30d50 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
30d60 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e  on_v2() is not N
30d70 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20  ULL,.** then it 
30d80 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f  is destructor fo
30d90 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
30da0 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20  n data pointer. 
30db0 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 74  .** The destruct
30dc0 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  or is invoked wh
30dd0 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  en the function 
30de0 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68  is deleted, eith
30df0 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f  er by being.** o
30e00 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65  verloaded or whe
30e10 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
30e20 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
30e30 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74  .)^.** ^The dest
30e40 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69  ructor is also i
30e50 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61  nvoked if the ca
30e60 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ll to.** sqlite3
30e70 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
30e80 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20  _v2() fails..** 
30e90 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 75  ^When the destru
30ea0 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66  ctor callback of
30eb0 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d   the tenth param
30ec0 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c  eter is invoked,
30ed0 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64   it.** is passed
30ee0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
30ef0 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63 6f  nt which is a co
30f00 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  py of the applic
30f10 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70  ation data .** p
30f20 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73  ointer which was
30f30 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61 6d   the fifth param
30f40 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
30f50 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
30f60 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  v2()..**.** ^It 
30f70 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
30f80 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c  register multipl
30f90 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
30fa0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a  s of the same.**
30fb0 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20   functions with 
30fc0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75  the same name bu
30fd0 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69  t with either di
30fe0 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20  ffering numbers 
30ff0 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20  of.** arguments 
31000 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65  or differing pre
31010 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
31020 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20  dings.  ^SQLite 
31030 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20  will use.** the 
31040 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74  implementation t
31050 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79  hat most closely
31060 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79   matches the way
31070 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a   in which the.**
31080 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
31090 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74   used.  ^A funct
310a0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
310b0 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65  on with a non-ne
310c0 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70  gative.** nArg p
310d0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65  arameter is a be
310e0 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  tter match than 
310f0 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  a function imple
31100 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a  mentation with.*
31110 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72  * a negative nAr
31120 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  g.  ^A function 
31130 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72  where the prefer
31140 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
31150 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65  g.** matches the
31160 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69   database encodi
31170 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a  ng is a better.*
31180 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  * match than a f
31190 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
311a0 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69  e encoding is di
311b0 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41  fferent.  .** ^A
311c0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
311d0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
311e0 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65  ference is betwe
311f0 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55  en UTF16le and U
31200 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63  TF16be.** is a c
31210 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e  loser match than
31220 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
31230 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
31240 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20  ifference is.** 
31250 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64  between UTF8 and
31260 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42   UTF16..**.** ^B
31270 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e  uilt-in function
31280 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61  s may be overloa
31290 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69  ded by new appli
312a0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
312b0 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  unctions..**.** 
312c0 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  ^An application-
312d0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
312e0 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
312f0 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53   call other.** S
31300 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
31310 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68  .  However, such
31320 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a   calls must not.
31330 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ** close the dat
31340 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
31350 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72   nor finalize or
31360 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61   reset the prepa
31370 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
31380 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75   in which the fu
31390 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
313a0 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  g..*/.int sqlite
313b0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
313c0 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  n(.  sqlite3 *db
313d0 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
313e0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
313f0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
31400 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
31410 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
31420 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
31430 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
31440 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
31450 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
31460 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31470 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
31480 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
31490 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
314a0 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74  context*).);.int
314b0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
314c0 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71  function16(.  sq
314d0 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
314e0 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69  st void *zFuncti
314f0 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
31500 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
31510 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
31520 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
31530 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
31540 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
31550 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
31560 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
31570 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
31580 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
31590 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
315a0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
315b0 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
315c0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
315d0 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  n_v2(.  sqlite3 
315e0 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
315f0 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
31600 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
31610 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
31620 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
31630 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
31640 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
31650 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
31660 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
31670 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
31680 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
31690 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
316a0 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
316b0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20  e3_context*),.  
316c0 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
316d0 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
316e0 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20   CAPI3REF: Text 
316f0 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20  Encodings.**.** 
31700 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64  These constant d
31710 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f  efine integer co
31720 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65  des that represe
31730 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a  nt the various.*
31740 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  * text encodings
31750 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
31760 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
31770 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20   SQLITE_UTF8    
31780 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
31790 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20   SQLITE_UTF16LE 
317a0 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
317b0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20   SQLITE_UTF16BE 
317c0 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
317d0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20   SQLITE_UTF16   
317e0 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55         4    /* U
317f0 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  se native byte o
31800 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rder */.#define 
31810 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20  SQLITE_ANY      
31820 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 44 65        5    /* De
31830 70 72 65 63 61 74 65 64 20 2a 2f 0a 23 64 65 66  precated */.#def
31840 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
31850 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f  _ALIGNED  8    /
31860 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
31870 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20  _collation only 
31880 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
31890 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 46 6c 61  EF: Function Fla
318a0 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  gs.**.** These c
318b0 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20  onstants may be 
318c0 4f 52 65 64 20 74 6f 67 65 74 68 65 72 20 77 69  ORed together wi
318d0 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
318e0 54 45 5f 55 54 46 38 20 7c 20 70 72 65 66 65 72  TE_UTF8 | prefer
318f0 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
31900 67 5d 20 61 73 20 74 68 65 20 66 6f 75 72 74 68  g] as the fourth
31910 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
31920 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
31930 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b 73 71  function()], [sq
31940 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
31950 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a  ction16()], or.*
31960 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
31970 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 5d  e_function_v2()]
31980 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
31990 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49  ITE_DETERMINISTI
319a0 43 20 20 20 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a  C    0x800../*.*
319b0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72  * CAPI3REF: Depr
319c0 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73  ecated Functions
319d0 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a  .** DEPRECATED.*
319e0 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
319f0 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63  ions are [deprec
31a00 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72  ated].  In order
31a10 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20   to maintain.** 
31a20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
31a30 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64  ibility with old
31a40 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66  er code, these f
31a50 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75  unctions continu
31a60 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70  e .** to be supp
31a70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c  orted.  However,
31a80 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
31a90 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a  s should avoid.*
31aa0 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65  * the use of the
31ab0 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  se functions.  T
31ac0 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65  o help encourage
31ad0 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64   people to avoid
31ae0 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20  .** using these 
31af0 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72  functions, we ar
31b00 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74  e not going to t
31b10 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65  ell you what the
31b20 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  y do..*/.#ifndef
31b30 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50   SQLITE_OMIT_DEP
31b40 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44  RECATED.SQLITE_D
31b50 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
31b60 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
31b70 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  count(sqlite3_co
31b80 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  ntext*);.SQLITE_
31b90 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
31ba0 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73  qlite3_expired(s
31bb0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53  qlite3_stmt*);.S
31bc0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
31bd0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61   int sqlite3_tra
31be0 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73  nsfer_bindings(s
31bf0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71  qlite3_stmt*, sq
31c00 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
31c10 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
31c20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62  int sqlite3_glob
31c30 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29  al_recover(void)
31c40 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
31c50 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33  TED void sqlite3
31c60 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28  _thread_cleanup(
31c70 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45  void);.SQLITE_DE
31c80 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
31c90 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72  ite3_memory_alar
31ca0 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  m(void(*)(void*,
31cb0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e  sqlite3_int64,in
31cc0 74 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  t),.            
31cd0 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 2a 2c            void*,
31ce0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
31cf0 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
31d00 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e  PI3REF: Obtainin
31d10 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50  g SQL Function P
31d20 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a  arameter Values.
31d30 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67  **.** The C-lang
31d40 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  uage implementat
31d50 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74  ion of SQL funct
31d60 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
31d70 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73  tes uses.** this
31d80 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63   set of interfac
31d90 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63  e routines to ac
31da0 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74  cess the paramet
31db0 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20  er values on.** 
31dc0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  the function or 
31dd0 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a  aggregate..**.**
31de0 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20   The xFunc (for 
31df0 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73  scalar functions
31e00 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20  ) or xStep (for 
31e10 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61  aggregates) para
31e20 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71  meters.** to [sq
31e30 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
31e40 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
31e50 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
31e60 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65  ction16()].** de
31e70 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74  fine callbacks t
31e80 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
31e90 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
31ea0 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a  and aggregates..
31eb0 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72 61 6d  ** The 3rd param
31ec0 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61  eter to these ca
31ed0 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72  llbacks is an ar
31ee0 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
31ef0 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64  to.** [protected
31f00 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
31f10 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20  objects.  There 
31f20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f  is one [sqlite3_
31f30 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f  value] object fo
31f40 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65  r.** each parame
31f50 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66  ter to the SQL f
31f60 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20  unction.  These 
31f70 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
31f80 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20  d to.** extract 
31f90 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20  values from the 
31fa0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
31fb0 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  objects..**.** T
31fc0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
31fd0 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72  rk only with [pr
31fe0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
31ff0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
32000 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
32010 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74  o use these rout
32020 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72  ines on an [unpr
32030 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
32040 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74  value].** object
32050 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
32060 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
32070 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
32080 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20  tines work just 
32090 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70  like the corresp
320a0 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61  onding [column a
320b0 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
320c0 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
320d0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
320e0 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72  ake a single [pr
320f0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
32100 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a  value] object.**
32110 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64   pointer instead
32120 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73   of a [sqlite3_s
32130 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e  tmt*] pointer an
32140 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c  d an integer col
32150 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a  umn number..**.*
32160 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
32170 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e  alue_text16() in
32180 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73  terface extracts
32190 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
321a0 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76  .** in the nativ
321b0 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20  e byte-order of 
321c0 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65  the host machine
321d0 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
321e0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
321f0 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
32200 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29  value_text16le()
32210 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65   interfaces.** e
32220 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74  xtract UTF-16 st
32230 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64  rings as big-end
32240 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65  ian and little-e
32250 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65  ndian respective
32260 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ly..**.** ^(The 
32270 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
32280 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74  meric_type() int
32290 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
322a0 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65  to apply.** nume
322b0 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20  ric affinity to 
322c0 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73  the value.  This
322d0 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61   means that an a
322e0 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64  ttempt is.** mad
322f0 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  e to convert the
32300 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74   value to an int
32310 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67  eger or floating
32320 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73   point.  If.** s
32330 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  uch a conversion
32340 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74   is possible wit
32350 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66  hout loss of inf
32360 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68  ormation (in oth
32370 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20  er.** words, if 
32380 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73  the value is a s
32390 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73  tring that looks
323a0 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a   like a number).
323b0 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76  ** then the conv
323c0 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72  ersion is perfor
323d0 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  med.  Otherwise 
323e0 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  no conversion oc
323f0 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51  curs..** The [SQ
32400 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
32410 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63  atatype] after c
32420 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74  onversion is ret
32430 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50  urned.)^.**.** P
32440 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63  lease pay partic
32450 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74  ular attention t
32460 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20  o the fact that 
32470 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75  the pointer retu
32480 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  rned.** from [sq
32490 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
324a0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
324b0 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a  lue_text()], or.
324c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
324d0 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20  e_text16()] can 
324e0 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62  be invalidated b
324f0 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63  y a subsequent c
32500 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
32510 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
32520 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
32530 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73  e_bytes16()], [s
32540 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
32550 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
32560 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
32570 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  6()]..**.** Thes
32580 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
32590 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
325a0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61  he same thread a
325b0 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  s.** the SQL fun
325c0 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c  ction that suppl
325d0 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ied the [sqlite3
325e0 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74  _value*] paramet
325f0 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  ers..*/.const vo
32600 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
32610 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76  e_blob(sqlite3_v
32620 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
32630 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
32640 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
32650 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
32660 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  ue_bytes16(sqlit
32670 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62  e3_value*);.doub
32680 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le sqlite3_value
32690 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
326a0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
326b0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73  ite3_value_int(s
326c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
326d0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
326e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36  lite3_value_int6
326f0 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  4(sqlite3_value*
32700 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  );.const unsigne
32710 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
32720 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74  value_text(sqlit
32730 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
32740 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
32750 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c  value_text16(sql
32760 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
32770 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
32780 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
32790 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
327a0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
327b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
327c0 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16be(sqlite3_val
327d0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
327e0 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c  3_value_type(sql
327f0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
32800 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
32810 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c  numeric_type(sql
32820 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f  ite3_value*);../
32830 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
32840 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20  btain Aggregate 
32850 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
32860 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74  .**.** Implement
32870 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67  ations of aggreg
32880 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
32890 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f  s use this.** ro
328a0 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74  utine to allocat
328b0 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f  e memory for sto
328c0 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65  ring their state
328d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
328e0 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69  st time the sqli
328f0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
32900 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69  ntext(C,N) routi
32910 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a  ne is called .**
32920 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
32930 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  r aggregate func
32940 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  tion, SQLite.** 
32950 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d  allocates N of m
32960 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75  emory, zeroes ou
32970 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61  t that memory, a
32980 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
32990 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e  nter.** to the n
329a0 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73  ew memory. ^On s
329b0 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
329c0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  uent calls to.**
329d0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
329e0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72  te_context() for
329f0 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
32a00 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73  ate function ins
32a10 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61  tance,.** the sa
32a20 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74  me buffer is ret
32a30 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f  urned.  Sqlite3_
32a40 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
32a50 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a  t() is normally.
32a60 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66  ** called once f
32a70 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69  or each invocati
32a80 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20  on of the xStep 
32a90 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65  callback and the
32aa0 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69  n one.** last ti
32ab0 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e  me when the xFin
32ac0 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  al callback is i
32ad0 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20  nvoked.  ^(When 
32ae0 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a  no rows match.**
32af0 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75   an aggregate qu
32b00 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29  ery, the xStep()
32b10 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   callback of the
32b20 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
32b30 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ion.** implement
32b40 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63  ation is never c
32b50 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c  alled and xFinal
32b60 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61  () is called exa
32b70 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e  ctly once..** In
32b80 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71   those cases, sq
32b90 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
32ba0 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20  context() might 
32bb0 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68  be called for th
32bc0 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20  e.** first time 
32bd0 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e  from within xFin
32be0 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  al().)^.**.** ^T
32bf0 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
32c00 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
32c10 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
32c20 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
32c30 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73 74 20   .** when first 
32c40 63 61 6c 6c 65 64 20 69 66 20 4e 20 69 73 20 6c  called if N is l
32c50 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
32c60 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20  l to zero or if 
32c70 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  a memory.** allo
32c80 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72  cate error occur
32c90 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61  s..**.** ^(The a
32ca0 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61  mount of space a
32cb0 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
32cc0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
32cd0 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a  ntext(C,N) is.**
32ce0 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74   determined by t
32cf0 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f  he N parameter o
32d00 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66  n first successf
32d10 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69  ul call.  Changi
32d20 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20  ng the.** value 
32d30 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65  of N in subseque
32d40 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  nt call to sqlit
32d50 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
32d60 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a  text() within.**
32d70 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
32d80 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73  ate function ins
32d90 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72  tance will not r
32da0 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  esize the memory
32db0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29  .** allocation.)
32dc0 5e 20 20 57 69 74 68 69 6e 20 74 68 65 20 78 46  ^  Within the xF
32dd0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69  inal callback, i
32de0 74 20 69 73 20 63 75 73 74 6f 6d 61 72 79 20 74  t is customary t
32df0 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20  o set.** N=0 in 
32e00 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
32e10 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
32e20 78 74 28 43 2c 4e 29 20 73 6f 20 74 68 61 74 20  xt(C,N) so that 
32e30 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73  no .** pointless
32e40 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
32e50 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a  ons occur..**.**
32e60 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74   ^SQLite automat
32e70 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65  ically frees the
32e80 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65   memory allocate
32e90 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33  d by .** sqlite3
32ea0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
32eb0 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 61 67  xt() when the ag
32ec0 67 72 65 67 61 74 65 20 71 75 65 72 79 20 63 6f  gregate query co
32ed0 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  ncludes..**.** T
32ee0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
32ef0 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70  er must be a cop
32f00 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  y of the.** [sql
32f10 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53  ite3_context | S
32f20 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74  QL function cont
32f30 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65  ext] that is the
32f40 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
32f50 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70  .** to the xStep
32f60 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62   or xFinal callb
32f70 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74  ack routine that
32f80 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
32f90 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e  aggregate.** fun
32fa0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
32fb0 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
32fc0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
32fd0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
32fe0 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67   which.** the ag
32ff0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
33000 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
33010 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
33020 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
33030 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext(sqlite3_cont
33040 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73  ext*, int nBytes
33050 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33060 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f  EF: User Data Fo
33070 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  r Functions.**.*
33080 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75  * ^The sqlite3_u
33090 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72  ser_data() inter
330a0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
330b0 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
330c0 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74  inter that was t
330d0 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72  he pUserData par
330e0 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20  ameter (the 5th 
330f0 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
33100 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
33110 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
33120 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
33130 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
33140 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
33150 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
33160 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
33170 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
33180 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
33190 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
331a0 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
331b0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
331c0 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
331d0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
331e0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
331f0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
33200 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
33210 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65  user_data(sqlite
33220 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
33230 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
33240 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
33250 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a  n For Functions.
33260 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
33270 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
33280 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  ndle() interface
33290 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
332a0 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
332b0 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61  r to the [databa
332c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
332d0 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
332e0 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
332f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
33300 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
33310 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
33320 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
33330 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
33340 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
33350 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
33360 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
33370 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65  ction..*/.sqlite
33380 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  3 *sqlite3_conte
33390 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c  xt_db_handle(sql
333a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
333b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
333c0 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69   Function Auxili
333d0 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54  ary Data.**.** T
333e0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 6d  hese functions m
333f0 61 79 20 62 65 20 75 73 65 64 20 62 79 20 28 6e  ay be used by (n
33400 6f 6e 2d 61 67 67 72 65 67 61 74 65 29 20 53 51  on-aggregate) SQ
33410 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a  L functions to.*
33420 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61  * associate meta
33430 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65  data with argume
33440 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68  nt values. If th
33450 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20  e same value is 
33460 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c  passed to.** mul
33470 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e  tiple invocation
33480 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51  s of the same SQ
33490 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e  L function durin
334a0 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f  g query executio
334b0 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65  n, under.** some
334c0 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74   circumstances t
334d0 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65  he associated me
334e0 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72  tadata may be pr
334f0 65 73 65 72 76 65 64 2e 20 20 41 6e 20 65 78 61  eserved.  An exa
33500 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 68 65 72 65  mple.** of where
33510 20 74 68 69 73 20 6d 69 67 68 74 20 62 65 20 75   this might be u
33520 73 65 66 75 6c 20 69 73 20 69 6e 20 61 20 72 65  seful is in a re
33530 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e  gular-expression
33540 20 6d 61 74 63 68 69 6e 67 0a 2a 2a 20 66 75 6e   matching.** fun
33550 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69  ction. The compi
33560 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  led version of t
33570 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  he regular expre
33580 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 73 74 6f  ssion can be sto
33590 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61  red as.** metada
335a0 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ta associated wi
335b0 74 68 20 74 68 65 20 70 61 74 74 65 72 6e 20 73  th the pattern s
335c0 74 72 69 6e 67 2e 20 20 0a 2a 2a 20 54 68 65 6e  tring.  .** Then
335d0 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
335e0 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 20 72  pattern string r
335f0 65 6d 61 69 6e 73 20 74 68 65 20 73 61 6d 65 2c  emains the same,
33600 0a 2a 2a 20 74 68 65 20 63 6f 6d 70 69 6c 65 64  .** the compiled
33610 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
33620 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65  ion can be reuse
33630 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  d on multiple.**
33640 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
33650 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
33660 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  n..**.** ^The sq
33670 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
33680 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
33690 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
336a0 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a  to the metadata.
336b0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79  ** associated by
336c0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
336d0 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74  _auxdata() funct
336e0 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68  ion with the Nth
336f0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c   argument.** val
33700 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ue to the applic
33710 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
33720 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 74 68 65 72  nction. ^If ther
33730 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 61  e is no metadata
33740 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
33750 69 74 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ith the function
33760 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 69 73 20   argument, this 
33770 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
33780 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 0a  ata() interface.
33790 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  ** returns a NUL
337a0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
337b0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65   ^The sqlite3_se
337c0 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
337d0 58 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76  X) interface sav
337e0 65 73 20 50 20 61 73 20 6d 65 74 61 64 61 74 61  es P as metadata
337f0 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a   for the N-th.**
33800 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65   argument of the
33810 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
33820 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20  ined function.  
33830 5e 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63  ^Subsequent.** c
33840 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
33850 67 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29  get_auxdata(C,N)
33860 20 72 65 74 75 72 6e 20 50 20 66 72 6f 6d 20 74   return P from t
33870 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a  he most recent.*
33880 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  * sqlite3_set_au
33890 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 63  xdata(C,N,P,X) c
338a0 61 6c 6c 20 69 66 20 74 68 65 20 6d 65 74 61 64  all if the metad
338b0 61 74 61 20 69 73 20 73 74 69 6c 6c 20 76 61 6c  ata is still val
338c0 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66  id or.** NULL if
338d0 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 68 61   the metadata ha
338e0 73 20 62 65 65 6e 20 64 69 73 63 61 72 64 65 64  s been discarded
338f0 2e 0a 2a 2a 20 5e 41 66 74 65 72 20 65 61 63 68  ..** ^After each
33900 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
33910 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _set_auxdata(C,N
33920 2c 50 2c 58 29 20 77 68 65 72 65 20 58 20 69 73  ,P,X) where X is
33930 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51   not NULL,.** SQ
33940 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  Lite will invoke
33950 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
33960 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 20  function X with 
33970 70 61 72 61 6d 65 74 65 72 20 50 20 65 78 61 63  parameter P exac
33980 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68 65  tly.** once, whe
33990 6e 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69  n the metadata i
339a0 73 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20  s discarded..** 
339b0 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74  SQLite is free t
339c0 6f 20 64 69 73 63 61 72 64 20 74 68 65 20 6d 65  o discard the me
339d0 74 61 64 61 74 61 20 61 74 20 61 6e 79 20 74 69  tadata at any ti
339e0 6d 65 2c 20 69 6e 63 6c 75 64 69 6e 67 3a 20 3c  me, including: <
339f0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e  ul>.** <li> when
33a00 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
33a10 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  ng function para
33a20 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2c 20 6f  meter changes, o
33a30 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 5b  r.** <li> when [
33a40 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
33a50 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
33a60 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c  alize()] is call
33a70 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20  ed for the.**   
33a80 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74     SQL statement
33a90 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65  , or.** <li> whe
33aa0 6e 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  n sqlite3_set_au
33ab0 78 64 61 74 61 28 29 20 69 73 20 69 6e 76 6f 6b  xdata() is invok
33ac0 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 65 20  ed again on the 
33ad0 73 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20  same parameter, 
33ae0 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75 72 69 6e  or.** <li> durin
33af0 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  g the original s
33b00 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
33b10 74 61 28 29 20 63 61 6c 6c 20 77 68 65 6e 20 61  ta() call when a
33b20 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20 20 20 20   memory .**     
33b30 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
33b40 72 20 6f 63 63 75 72 73 2e 20 3c 2f 75 6c 3e 29  r occurs. </ul>)
33b50 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 65  ^.**.** Note the
33b60 20 6c 61 73 74 20 62 75 6c 6c 65 74 20 69 6e 20   last bullet in 
33b70 70 61 72 74 69 63 75 6c 61 72 2e 20 20 54 68 65  particular.  The
33b80 20 64 65 73 74 72 75 63 74 6f 72 20 58 20 69 6e   destructor X in
33b90 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74   .** sqlite3_set
33ba0 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58  _auxdata(C,N,P,X
33bb0 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65  ) might be calle
33bc0 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62  d immediately, b
33bd0 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 73 71 6c  efore the.** sql
33be0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
33bf0 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 76 65  () interface eve
33c00 6e 20 72 65 74 75 72 6e 73 2e 20 20 48 65 6e 63  n returns.  Henc
33c10 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
33c20 78 64 61 74 61 28 29 0a 2a 2a 20 73 68 6f 75 6c  xdata().** shoul
33c30 64 20 62 65 20 63 61 6c 6c 65 64 20 6e 65 61 72  d be called near
33c40 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
33c50 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
33c60 6e 74 61 74 69 6f 6e 20 61 6e 64 20 74 68 65 0a  ntation and the.
33c70 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  ** function impl
33c80 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c  ementation shoul
33c90 64 20 6e 6f 74 20 6d 61 6b 65 20 61 6e 79 20 75  d not make any u
33ca0 73 65 20 6f 66 20 50 20 61 66 74 65 72 0a 2a 2a  se of P after.**
33cb0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
33cc0 64 61 74 61 28 29 20 68 61 73 20 62 65 65 6e 20  data() has been 
33cd0 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  called..**.** ^(
33ce0 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74  In practice, met
33cf0 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76  adata is preserv
33d00 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74  ed between funct
33d10 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a  ion calls for.**
33d20 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
33d30 74 65 72 73 20 74 68 61 74 20 61 72 65 20 63 6f  ters that are co
33d40 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e 73 74  mpile-time const
33d50 61 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ants, including 
33d60 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65  literal.** value
33d70 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72  s and [parameter
33d80 73 5d 20 61 6e 64 20 65 78 70 72 65 73 73 69 6f  s] and expressio
33d90 6e 73 20 63 6f 6d 70 6f 73 65 64 20 66 72 6f 6d  ns composed from
33da0 20 74 68 65 20 73 61 6d 65 2e 29 5e 0a 2a 2a 0a   the same.)^.**.
33db0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
33dc0 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
33dd0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
33de0 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
33df0 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
33e00 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
33e10 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
33e20 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  get_auxdata(sqli
33e30 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
33e40 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  t N);.void sqlit
33e50 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73  e3_set_auxdata(s
33e60 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33e70 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76   int N, void*, v
33e80 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b  oid (*)(void*));
33e90 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
33ea0 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66  F: Constants Def
33eb0 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65  ining Special De
33ec0 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f  structor Behavio
33ed0 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72  r.**.** These ar
33ee0 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73  e special values
33ef0 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63   for the destruc
33f00 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73  tor that is pass
33f10 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20  ed in as the.** 
33f20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74  final argument t
33f30 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
33f40 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
33f50 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68  blob()].  ^If th
33f60 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20  e destructor.** 
33f70 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49  argument is SQLI
33f80 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65  TE_STATIC, it me
33f90 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
33fa0 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20  tent pointer is 
33fb0 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20  constant.** and 
33fc0 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67  will never chang
33fd0 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20  e.  It does not 
33fe0 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72  need to be destr
33ff0 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53  oyed.  ^The.** S
34000 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
34010 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74  value means that
34020 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c   the content wil
34030 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20  l likely change 
34040 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66  in.** the near f
34050 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53  uture and that S
34060 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b  QLite should mak
34070 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  e its own privat
34080 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  e copy of.** the
34090 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20   content before 
340a0 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  returning..**.**
340b0 20 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20   The typedef is 
340c0 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72  necessary to wor
340d0 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d  k around problem
340e0 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20  s in certain.** 
340f0 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 0a 2a  C++ compilers..*
34100 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28  /.typedef void (
34110 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  *sqlite3_destruc
34120 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29  tor_type)(void*)
34130 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ;.#define SQLITE
34140 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73  _STATIC      ((s
34150 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
34160 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e  r_type)0).#defin
34170 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  e SQLITE_TRANSIE
34180 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64  NT   ((sqlite3_d
34190 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d  estructor_type)-
341a0 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  1)../*.** CAPI3R
341b0 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20  EF: Setting The 
341c0 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c  Result Of An SQL
341d0 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20   Function.**.** 
341e0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
341f0 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78  re used by the x
34200 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63  Func or xFinal c
34210 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a  allbacks that.**
34220 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66   implement SQL f
34230 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
34240 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a  regates.  See.**
34250 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
34260 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
34270 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
34280 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
34290 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  * for additional
342a0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
342b0 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
342c0 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75  ons work very mu
342d0 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72  ch like the [par
342e0 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20  ameter binding] 
342f0 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e  family of.** fun
34300 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62  ctions used to b
34310 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f  ind values to ho
34320 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  st parameters in
34330 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
34340 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74  ents..** Refer t
34350 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d  o the [SQL param
34360 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74  eter] documentat
34370 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ion for addition
34380 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
34390 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
343a0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
343b0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
343c0 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
343d0 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
343e0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
343f0 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f  on to be the BLO
34400 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20  B whose content 
34410 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f  is pointed.** to
34420 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70   by the second p
34430 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69  arameter and whi
34440 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f  ch is N bytes lo
34450 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  ng where N is th
34460 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
34470 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
34480 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34490 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72  zeroblob() inter
344a0 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65  faces set the re
344b0 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
344c0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
344d0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
344e0 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e  e a BLOB contain
344f0 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20  ing all zero.** 
34500 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65  bytes and N byte
34510 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65  s in size, where
34520 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20   N is the value 
34530 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  of the 2nd param
34540 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
34550 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34560 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61  double() interfa
34570 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
34580 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
34590 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
345a0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
345b0 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
345c0 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  t value specifie
345d0 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20  d.** by its 2nd 
345e0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
345f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
34600 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
34610 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
34620 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f  rror16() functio
34630 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20  ns.** cause the 
34640 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20  implemented SQL 
34650 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f  function to thro
34660 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a  w an exception..
34670 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
34680 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  the string point
34690 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20  ed to by the.** 
346a0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
346b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
346c0 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74  error() or sqlit
346d0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
346e0 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65  6().** as the te
346f0 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d  xt of an error m
34700 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65  essage.  ^SQLite
34710 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
34720 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
34730 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
34740 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
34750 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53  r() as UTF-8. ^S
34760 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72  QLite.** interpr
34770 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66  ets the string f
34780 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
34790 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20  lt_error16() as 
347a0 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65  UTF-16 in native
347b0 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20  .** byte order. 
347c0 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
347d0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
347e0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
347f0 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
34800 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
34810 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68  ) is negative th
34820 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
34830 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  as the error.** 
34840 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74  message all text
34850 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20   up through the 
34860 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
34870 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  cter..** ^If the
34880 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
34890 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
348a0 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a  lt_error() or.**
348b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
348c0 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e  error16() is non
348d0 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53  -negative then S
348e0 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74  QLite takes that
348f0 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28   many.** bytes (
34900 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
34910 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
34920 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72  ameter as the er
34930 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20  ror message..** 
34940 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
34950 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
34960 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
34970 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74  rror16().** rout
34980 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76  ines make a priv
34990 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
349a0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
349b0 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  xt before.** the
349c0 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65  y return.  Hence
349d0 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  , the calling fu
349e0 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c  nction can deall
349f0 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69  ocate or.** modi
34a00 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65  fy the text afte
34a10 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69  r they return wi
34a20 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e  thout harm..** ^
34a30 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
34a40 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20  lt_error_code() 
34a50 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73  function changes
34a60 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a   the error code.
34a70 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53  ** returned by S
34a80 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c  QLite as a resul
34a90 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e  t of an error in
34aa0 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42   a function.  ^B
34ab0 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68  y default,.** th
34ac0 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  e error code is 
34ad0 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e  SQLITE_ERROR.  ^
34ae0 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  A subsequent cal
34af0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  l to sqlite3_res
34b00 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
34b10 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
34b20 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74  _error16() reset
34b30 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
34b40 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   to SQLITE_ERROR
34b50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
34b60 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
34b70 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72  r_toobig() inter
34b80 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69  face causes SQLi
34b90 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a  te to throw an.*
34ba0 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69  * error indicati
34bb0 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67  ng that a string
34bc0 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20   or BLOB is too 
34bd0 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e  long to represen
34be0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
34bf0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
34c00 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72  or_nomem() inter
34c10 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69  face causes SQLi
34c20 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a  te to throw an.*
34c30 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69  * error indicati
34c40 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79  ng that a memory
34c50 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
34c60 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
34c70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
34c80 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  t() interface se
34c90 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
34ca0 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
34cb0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
34cc0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
34cd0 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e   the 32-bit sign
34ce0 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61  ed integer.** va
34cf0 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  lue given in the
34d00 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
34d10 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
34d20 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e  esult_int64() in
34d30 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
34d40 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
34d50 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
34d60 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
34d70 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36  tion to be the 6
34d80 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
34d90 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69  eger.** value gi
34da0 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61  ven in the 2nd a
34db0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
34dc0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
34dd0 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66  lt_null() interf
34de0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
34df0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
34e00 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
34e10 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
34e20 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a   to be NULL..**.
34e30 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34e40 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73  result_text(), s
34e50 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
34e60 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  xt16(),.** sqlit
34e70 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
34e80 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65  le(), and sqlite
34e90 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
34ea0 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
34eb0 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e  * set the return
34ec0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70   value of the ap
34ed0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
34ee0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
34ef0 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e  .** a text strin
34f00 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65  g which is repre
34f10 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c  sented as UTF-8,
34f20 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
34f30 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54  yte order,.** UT
34f40 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69  F-16 little endi
34f50 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69  an, or UTF-16 bi
34f60 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63  g endian, respec
34f70 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69  tively..** ^SQLi
34f80 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78  te takes the tex
34f90 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68  t result from th
34fa0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72  e application fr
34fb0 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61  om.** the 2nd pa
34fc0 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73  rameter of the s
34fd0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
34fe0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  xt* interfaces..
34ff0 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70  ** ^If the 3rd p
35000 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
35010 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
35020 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
35030 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  ** is negative, 
35040 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
35050 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72  s result text fr
35060 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
35070 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20  eter.** through 
35080 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
35090 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66  haracter..** ^If
350a0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
350b0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
350c0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
350d0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
350e0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
350f0 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73  en as many bytes
35100 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73   (not characters
35110 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a  ) of the text.**
35120 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
35130 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
35140 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68   are taken as th
35150 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
35160 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f  fined.** functio
35170 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68  n result.  If th
35180 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
35190 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
351a0 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74   then it.** must
351b0 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66   be the byte off
351c0 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72  set into the str
351d0 69 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e 55  ing where the NU
351e0 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75  L terminator wou
351f0 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20  ld.** appear if 
35200 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65  the string where
35210 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e   NUL terminated.
35220 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61    If any NUL cha
35230 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a  racters occur.**
35240 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61   in the string a
35250 74 20 61 20 62 79 74 65 20 6f 66 66 73 65 74 20  t a byte offset 
35260 74 68 61 74 20 69 73 20 6c 65 73 73 20 74 68 61  that is less tha
35270 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  n the value of t
35280 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65  he 3rd.** parame
35290 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ter, then the re
352a0 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77  sulting string w
352b0 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65  ill contain embe
352c0 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68  dded NULs and th
352d0 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65  e.** result of e
352e0 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61  xpressions opera
352f0 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20  ting on strings 
35300 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55  with embedded NU
35310 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  Ls is undefined.
35320 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
35330 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
35340 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35350 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
35360 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
35370 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20  esult_blob is a 
35380 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
35390 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61  , then SQLite ca
353a0 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63  lls that.** func
353b0 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74  tion as the dest
353c0 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65  ructor on the te
353d0 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c  xt or BLOB resul
353e0 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a  t when it has.**
353f0 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
35400 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  that result..** 
35410 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
35420 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
35430 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
35440 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20  * interfaces or 
35450 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  to.** sqlite3_re
35460 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
35470 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
35480 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  t SQLITE_STATIC,
35490 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20   then SQLite.** 
354a0 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
354b0 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65   text or BLOB re
354c0 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74  sult is in const
354d0 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ant space and do
354e0 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74  es not.** copy t
354f0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
35500 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20  e parameter nor 
35510 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f  call a destructo
35520 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74  r on the content
35530 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20  .** when it has 
35540 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
35550 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  hat result..** ^
35560 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
35570 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
35580 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
35590 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
355a0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
355b0 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65  _blob is the spe
355c0 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51  cial constant SQ
355d0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a  LITE_TRANSIENT.*
355e0 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61  * then SQLite ma
355f0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
35600 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70  e result into sp
35610 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ace obtained fro
35620 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  m.** from [sqlit
35630 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66  e3_malloc()] bef
35640 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a  ore it returns..
35650 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
35660 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
35670 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
35680 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
35690 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
356a0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
356b0 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20  on to be a copy 
356c0 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63  the.** [unprotec
356d0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
356e0 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  e] object specif
356f0 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70  ied by the 2nd p
35700 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a  arameter.  ^The.
35710 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
35720 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
35730 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ace makes a copy
35740 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
35750 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68  _value].** so th
35760 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
35770 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64  value] specified
35780 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
35790 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a  r may change or.
357a0 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ** be deallocate
357b0 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
357c0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72  result_value() r
357d0 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68  eturns without h
357e0 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74  arm..** ^A [prot
357f0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
35800 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20  lue] object may 
35810 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77  always be used w
35820 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  here an.** [unpr
35830 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
35840 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73  value] object is
35850 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69   required, so ei
35860 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20  ther.** kind of 
35870 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
35880 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73  object can be us
35890 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74  ed with this int
358a0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66  erface..**.** If
358b0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
358c0 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
358d0 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65  within the diffe
358e0 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74  rent thread.** t
358f0 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74  han the one cont
35900 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69  aining the appli
35910 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
35920 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63  unction that rec
35930 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71  eived.** the [sq
35940 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70  lite3_context] p
35950 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75  ointer, the resu
35960 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
35970 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  d..*/.void sqlit
35980 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73  e3_result_blob(s
35990 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
359a0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
359b0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
359c0 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
359d0 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73  _result_double(s
359e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
359f0 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73   double);.void s
35a00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
35a10 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ror(sqlite3_cont
35a20 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  ext*, const char
35a30 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
35a40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
35a50 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  or16(sqlite3_con
35a60 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
35a70 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  d*, int);.void s
35a80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
35a90 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74  ror_toobig(sqlit
35aa0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
35ab0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
35ac0 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71  t_error_nomem(sq
35ad0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
35ae0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
35af0 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28  sult_error_code(
35b00 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35b10 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
35b20 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28  ite3_result_int(
35b30 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35b40 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
35b50 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36  ite3_result_int6
35b60 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  4(sqlite3_contex
35b70 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  t*, sqlite3_int6
35b80 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  4);.void sqlite3
35b90 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c  _result_null(sql
35ba0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
35bb0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
35bc0 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ult_text(sqlite3
35bd0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
35be0 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69   char*, int, voi
35bf0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
35c00 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
35c10 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  t_text16(sqlite3
35c20 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
35c30 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
35c40 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
35c50 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
35c60 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74  t_text16le(sqlit
35c70 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
35c80 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
35c90 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
35ca0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
35cb0 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  lt_text16be(sqli
35cc0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
35cd0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76  nst void*, int,v
35ce0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
35cf0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
35d00 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ult_value(sqlite
35d10 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69  3_context*, sqli
35d20 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69  te3_value*);.voi
35d30 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
35d40 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
35d50 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
35d60 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  n);../*.** CAPI3
35d70 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20  REF: Define New 
35d80 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e  Collating Sequen
35d90 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ces.**.** ^These
35da0 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20   functions add, 
35db0 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66  remove, or modif
35dc0 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20  y a [collation] 
35dd0 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69  associated.** wi
35de0 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
35df0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
35e00 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69  cified as the fi
35e10 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
35e20 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
35e30 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69   the collation i
35e40 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  s a UTF-8 string
35e50 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  .** for sqlite3_
35e60 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
35e70 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
35e80 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
35e90 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54  v2().** and a UT
35ea0 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
35eb0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
35ec0 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
35ed0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
35ee0 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e  )..** ^Collation
35ef0 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70   names that comp
35f00 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64  are equal accord
35f10 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ing to [sqlite3_
35f20 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a  strnicmp()] are.
35f30 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  ** considered to
35f40 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d   be the same nam
35f50 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74  e..**.** ^(The t
35f60 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65  hird argument (e
35f70 54 65 78 74 52 65 70 29 20 6d 75 73 74 20 62 65  TextRep) must be
35f80 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73   one of the cons
35f90 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  tants:.** <ul>.*
35fa0 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
35fb0 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  TF8],.** <li> [S
35fc0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a  QLITE_UTF16LE],.
35fd0 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
35fe0 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69  UTF16BE],.** <li
35ff0 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  > [SQLITE_UTF16]
36000 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
36010 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
36020 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  ED]..** </ul>)^.
36030 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65 70  ** ^The eTextRep
36040 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d   argument determ
36050 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e  ines the encodin
36060 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73  g of strings pas
36070 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f  sed.** to the co
36080 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
36090 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c   callback, xCall
360a0 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  back..** ^The [S
360b0 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64  QLITE_UTF16] and
360c0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
360d0 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66  LIGNED] values f
360e0 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66  or eTextRep.** f
360f0 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20  orce strings to 
36100 62 65 20 55 54 46 31 36 20 77 69 74 68 20 6e 61  be UTF16 with na
36110 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
36120 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
36130 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20  _UTF16_ALIGNED] 
36140 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52  value for eTextR
36150 65 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67  ep forces string
36160 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e  s to begin.** on
36170 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64   an even byte ad
36180 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  dress..**.** ^Th
36190 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
361a0 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61  t, pArg, is an a
361b0 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
361c0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
361d0 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67  passed.** throug
361e0 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  h as the first a
361f0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63  rgument to the c
36200 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
36210 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  n callback..**.*
36220 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67  * ^The fifth arg
36230 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b  ument, xCallback
36240 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  , is a pointer t
36250 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  o the collating 
36260 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75  function..** ^Mu
36270 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67  ltiple collating
36280 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62   functions can b
36290 65 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  e registered usi
362a0 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  ng the same name
362b0 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66   but.** with dif
362c0 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20  ferent eTextRep 
362d0 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53  parameters and S
362e0 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77  QLite will use w
362f0 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63  hichever.** func
36300 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68  tion requires th
36310 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
36320 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d  f data transform
36330 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68  ation..** ^If th
36340 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75  e xCallback argu
36350 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65  ment is NULL the
36360 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  n the collating 
36370 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64  function is.** d
36380 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61  eleted.  ^When a
36390 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  ll collating fun
363a0 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68  ctions having th
363b0 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20  e same name are 
363c0 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74  deleted,.** that
363d0 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   collation is no
363e0 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a   longer usable..
363f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61  **.** ^The colla
36400 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ting function ca
36410 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
36420 64 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66  d with a copy of
36430 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70   the pArg .** ap
36440 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
36450 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20  ointer and with 
36460 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74  two strings in t
36470 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63  he encoding spec
36480 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  ified.** by the 
36490 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e  eTextRep argumen
364a0 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e  t.  The collatin
364b0 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  g function must 
364c0 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74  return an.** int
364d0 65 67 65 72 20 74 68 61 74 20 69 73 20 6e 65 67  eger that is neg
364e0 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20  ative, zero, or 
364f0 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74  positive.** if t
36500 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20  he first string 
36510 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71  is less than, eq
36520 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74  ual to, or great
36530 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f  er than the seco
36540 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  nd,.** respectiv
36550 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e  ely.  A collatin
36560 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  g function must 
36570 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68  always return th
36580 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a  e same answer.**
36590 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20   given the same 
365a0 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20  inputs.  If two 
365b0 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e  or more collatin
365c0 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  g functions are 
365d0 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f  registered.** to
365e0 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74   the same collat
365f0 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20  ion name (using 
36600 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52  different eTextR
36610 65 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20  ep values) then 
36620 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65  all.** must give
36630 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61   an equivalent a
36640 6e 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b  nswer when invok
36650 65 64 20 77 69 74 68 20 65 71 75 69 76 61 6c 65  ed with equivale
36660 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54  nt strings..** T
36670 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
36680 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20  ction must obey 
36690 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72  the following pr
366a0 6f 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c  operties for all
366b0 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42  .** strings A, B
366c0 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c  , and C:.**.** <
366d0 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  ol>.** <li> If A
366e0 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a  ==B then B==A..*
366f0 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61  * <li> If A==B a
36700 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d  nd B==C then A==
36710 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26  C..** <li> If A&
36720 6c 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41  lt;B THEN B&gt;A
36730 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c  ..** <li> If A&l
36740 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74  t;B and B&lt;C t
36750 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c  hen A&lt;C..** <
36760 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  /ol>.**.** If a 
36770 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
36780 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20  on fails any of 
36790 74 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72  the above constr
367a0 61 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a  aints and that.*
367b0 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  * collating func
367c0 74 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65  tion is  registe
367d0 72 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68  red and used, th
367e0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
367f0 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20  of SQLite.** is 
36800 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
36810 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72   ^The sqlite3_cr
36820 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
36830 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  2() works like s
36840 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
36850 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74  llation().** wit
36860 68 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74  h the addition t
36870 68 61 74 20 74 68 65 20 78 44 65 73 74 72 6f 79  hat the xDestroy
36880 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
36890 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65  oked on pArg whe
368a0 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69  n.** the collati
368b0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64  ng function is d
368c0 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c  eleted..** ^Coll
368d0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
368e0 61 72 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e  are deleted when
368f0 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69   they are overri
36900 64 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a  dden by later.**
36910 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f   calls to the co
36920 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  llation creation
36930 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68   functions or wh
36940 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  en the.** [datab
36950 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
36960 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20  is closed using 
36970 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
36980 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44  ]..**.** ^The xD
36990 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20  estroy callback 
369a0 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61  is <u>not</u> ca
369b0 6c 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20  lled if the .** 
369c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
369d0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75  ollation_v2() fu
369e0 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41  nction fails.  A
369f0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
36a00 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
36a10 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
36a20 69 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20  ion_v2() with a 
36a30 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f  non-NULL xDestro
36a40 79 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  y argument shoul
36a50 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20  d .** check the 
36a60 72 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20  return code and 
36a70 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61  dispose of the a
36a80 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
36a90 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73  pointer.** thems
36aa0 65 6c 76 65 73 20 72 61 74 68 65 72 20 74 68 61  elves rather tha
36ab0 6e 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69  n expecting SQLi
36ac0 74 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20  te to deal with 
36ad0 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20  it for them..** 
36ae0 54 68 69 73 20 69 73 20 64 69 66 66 65 72 65 6e  This is differen
36af0 74 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68  t from every oth
36b00 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
36b10 61 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73  ace.  The incons
36b20 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75  istency .** is u
36b30 6e 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63  nfortunate but c
36b40 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  annot be changed
36b50 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
36b60 67 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20  g backwards .** 
36b70 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
36b80 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20  *.** See also:  
36b90 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
36ba0 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64  on_needed()] and
36bb0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
36bc0 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e  ion_needed16()].
36bd0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
36be0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
36bf0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
36c00 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
36c10 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
36c20 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41  Rep, .  void *pA
36c30 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  rg,.  int(*xComp
36c40 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
36c50 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
36c60 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69  onst void*).);.i
36c70 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
36c80 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a  e_collation_v2(.
36c90 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
36ca0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
36cb0 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  , .  int eTextRe
36cc0 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67  p, .  void *pArg
36cd0 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
36ce0 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
36cf0 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
36d00 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69  st void*),.  voi
36d10 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69  d(*xDestroy)(voi
36d20 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  d*).);.int sqlit
36d30 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
36d40 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ion16(.  sqlite3
36d50 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  *, .  const void
36d60 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65   *zName,.  int e
36d70 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
36d80 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78   *pArg,.  int(*x
36d90 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
36da0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
36db0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
36dc0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
36dd0 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65  EF: Collation Ne
36de0 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  eded Callbacks.*
36df0 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68  *.** ^To avoid h
36e00 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65  aving to registe
36e10 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20  r all collation 
36e20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65  sequences before
36e30 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63   a database.** c
36e40 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69  an be used, a si
36e50 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ngle callback fu
36e60 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65  nction may be re
36e70 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68  gistered with th
36e80 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
36e90 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65  onnection] to be
36ea0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
36eb0 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63  r an undefined c
36ec0 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
36ed0 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64  ence is required
36ee0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
36ef0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69  function is regi
36f00 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65  stered using the
36f10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
36f20 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c  on_needed() API,
36f30 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70  .** then it is p
36f40 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20  assed the names 
36f50 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c  of undefined col
36f60 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
36f70 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65   as strings.** e
36f80 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e  ncoded in UTF-8.
36f90 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c   ^If sqlite3_col
36fa0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
36fb0 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68  ) is used,.** th
36fc0 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73  e names are pass
36fd0 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
36fe0 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62  machine native b
36ff0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41  yte order..** ^A
37000 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20   call to either 
37010 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65  function replace
37020 73 20 74 68 65 20 65 78 69 73 74 69 6e 67 20 63  s the existing c
37030 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20  ollation-needed 
37040 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
37050 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  ^(When the callb
37060 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ack is invoked, 
37070 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
37080 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63  nt passed is a c
37090 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65  opy.** of the se
370a0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
370b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
370c0 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a  on_needed() or.*
370d0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  * sqlite3_collat
370e0 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20  ion_needed16(). 
370f0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
37100 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61  ment is the data
37110 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
37120 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  on.  The third a
37130 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
37140 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  f [SQLITE_UTF8],
37150 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
37160 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  ],.** or [SQLITE
37170 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63  _UTF16LE], indic
37180 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64  ating the most d
37190 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66  esirable form of
371a0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a   the collation.*
371b0 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74  * sequence funct
371c0 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54  ion required.  T
371d0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
371e0 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
371f0 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72  of the.** requir
37200 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
37210 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  uence.)^.**.** T
37220 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
37230 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69  tion should regi
37240 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64  ster the desired
37250 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67   collation using
37260 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
37270 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d  ate_collation()]
37280 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
37290 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d  e_collation16()]
372a0 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
372b0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
372c0 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  n_v2()]..*/.int 
372d0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
372e0 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69  n_needed(.  sqli
372f0 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20  te3*, .  void*, 
37300 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
37310 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
37320 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61  extRep,const cha
37330 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  r*).);.int sqlit
37340 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
37350 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ded16(.  sqlite3
37360 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76  *, .  void*,.  v
37370 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
37380 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
37390 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  ep,const void*).
373a0 29 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54  );..#ifdef SQLIT
373b0 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a  E_HAS_CODEC./*.*
373c0 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65  * Specify the ke
373d0 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74  y for an encrypt
373e0 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68  ed database.  Th
373f0 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c  is routine shoul
37400 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72  d be.** called r
37410 69 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74  ight after sqlit
37420 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a  e3_open()..**.**
37430 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70   The code to imp
37440 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20  lement this API 
37450 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65  is not available
37460 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72   in the public r
37470 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c  elease.** of SQL
37480 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ite..*/.int sqli
37490 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74  te3_key(.  sqlit
374a0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
374b0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
374c0 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
374d0 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
374e0 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
374f0 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b  Key     /* The k
37500 65 79 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ey */.);.int sql
37510 69 74 65 33 5f 6b 65 79 5f 76 32 28 0a 20 20 73  ite3_key_v2(.  s
37520 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
37530 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
37540 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   Database to be 
37550 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e  rekeyed */.  con
37560 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65  st char *zDbName
37570 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  ,           /* N
37580 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
37590 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  ase */.  const v
375a0 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
375b0 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b  Key     /* The k
375c0 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
375d0 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f  Change the key o
375e0 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  n an open databa
375f0 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72  se.  If the curr
37600 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20  ent database is 
37610 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64  not.** encrypted
37620 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  , this routine w
37630 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20  ill encrypt it. 
37640 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e   If pNew==0 or n
37650 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64  New==0, the.** d
37660 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79  atabase is decry
37670 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  pted..**.** The 
37680 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  code to implemen
37690 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f  t this API is no
376a0 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  t available in t
376b0 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73  he public releas
376c0 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a  e.** of SQLite..
376d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
376e0 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20  ekey(.  sqlite3 
376f0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
37700 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
37710 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64  se to be rekeyed
37720 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
37730 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79   *pKey, int nKey
37740 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20       /* The new 
37750 6b 65 79 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  key */.);.int sq
37760 6c 69 74 65 33 5f 72 65 6b 65 79 5f 76 32 28 0a  lite3_rekey_v2(.
37770 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
37780 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37790 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
377a0 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
377b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e  const char *zDbN
377c0 61 6d 65 2c 20 20 20 20 20 20 20 20 20 20 20 2f  ame,           /
377d0 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  * Name of the da
377e0 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
377f0 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
37800 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
37810 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a  e new key */.);.
37820 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
37830 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65  he activation ke
37840 79 20 66 6f 72 20 61 20 53 45 45 20 64 61 74 61  y for a SEE data
37850 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a  base.  Unless .*
37860 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e  * activated, non
37870 65 20 6f 66 20 74 68 65 20 53 45 45 20 72 6f 75  e of the SEE rou
37880 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e  tines will work.
37890 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
378a0 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28 0a 20  _activate_see(. 
378b0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
378c0 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20  ssPhrase        
378d0 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68  /* Activation ph
378e0 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69  rase */.);.#endi
378f0 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  f..#ifdef SQLITE
37900 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a  _ENABLE_CEROD./*
37910 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
37920 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66  activation key f
37930 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74 61 62  or a CEROD datab
37940 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a  ase.  Unless .**
37950 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65   activated, none
37960 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20 72 6f   of the CEROD ro
37970 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b  utines will work
37980 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
37990 33 5f 61 63 74 69 76 61 74 65 5f 63 65 72 6f 64  3_activate_cerod
379a0 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
379b0 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20  zPassPhrase     
379c0 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e     /* Activation
379d0 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65   phrase */.);.#e
379e0 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
379f0 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78  3REF: Suspend Ex
37a00 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68  ecution For A Sh
37a10 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54  ort Time.**.** T
37a20 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  he sqlite3_sleep
37a30 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  () function caus
37a40 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74  es the current t
37a50 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64  hread to suspend
37a60 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f   execution.** fo
37a70 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d  r at least a num
37a80 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
37a90 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69 6e  nds specified in
37aa0 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a   its parameter..
37ab0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65  **.** If the ope
37ac0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f  rating system do
37ad0 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73  es not support s
37ae0 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69  leep requests wi
37af0 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e  th.** millisecon
37b00 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f  d time resolutio
37b10 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65  n, then the time
37b20 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64   will be rounded
37b30 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65   up to.** the ne
37b40 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68  arest second. Th
37b50 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
37b60 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
37b70 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65  p actually.** re
37b80 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65  quested from the
37b90 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
37ba0 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  m is returned..*
37bb0 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70  *.** ^SQLite imp
37bc0 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74  lements this int
37bd0 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e  erface by callin
37be0 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a  g the xSleep().*
37bf0 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  * method of the 
37c00 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
37c10 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 49  _vfs] object.  I
37c20 66 20 74 68 65 20 78 53 6c 65 65 70 28 29 20 6d  f the xSleep() m
37c30 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20  ethod.** of the 
37c40 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 6e  default VFS is n
37c50 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 63  ot implemented c
37c60 6f 72 72 65 63 74 6c 79 2c 20 6f 72 20 6e 6f 74  orrectly, or not
37c70 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 74 0a   implemented at.
37c80 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e 20 74 68 65  ** all, then the
37c90 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c   behavior of sql
37ca0 69 74 65 33 5f 73 6c 65 65 70 28 29 20 6d 61 79  ite3_sleep() may
37cb0 20 64 65 76 69 61 74 65 20 66 72 6f 6d 20 74 68   deviate from th
37cc0 65 20 64 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a  e description.**
37cd0 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
37ce0 20 70 61 72 61 67 72 61 70 68 73 2e 0a 2a 2f 0a   paragraphs..*/.
37cf0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65  int sqlite3_slee
37d00 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  p(int);../*.** C
37d10 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
37d20 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64   The Folder Hold
37d30 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69  ing Temporary Fi
37d40 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74  les.**.** ^(If t
37d50 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61  his global varia
37d60 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ble is made to p
37d70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67  oint to a string
37d80 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65   which is.** the
37d90 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65   name of a folde
37da0 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74  r (a.k.a. direct
37db0 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74  ory), then all t
37dc0 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a  emporary files.*
37dd0 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c  * created by SQL
37de0 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61  ite when using a
37df0 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 74   built-in [sqlit
37e00 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 0a 2a 2a  e3_vfs | VFS].**
37e10 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20   will be placed 
37e20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f 72  in that director
37e30 79 2e 29 5e 20 20 5e 49 66 20 74 68 69 73 20 76  y.)^  ^If this v
37e40 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20  ariable.** is a 
37e50 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
37e60 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72  en SQLite perfor
37e70 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20  ms a search for 
37e80 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a  an appropriate.*
37e90 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
37ea0 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a   directory..**.*
37eb0 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  * Applications a
37ec0 72 65 20 73 74 72 6f 6e 67 6c 79 20 64 69 73 63  re strongly disc
37ed0 6f 75 72 61 67 65 64 20 66 72 6f 6d 20 75 73 69  ouraged from usi
37ee0 6e 67 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76  ng this global v
37ef0 61 72 69 61 62 6c 65 2e 0a 2a 2a 20 49 74 20 69  ariable..** It i
37f00 73 20 72 65 71 75 69 72 65 64 20 74 6f 20 73 65  s required to se
37f10 74 20 61 20 74 65 6d 70 6f 72 61 72 79 20 66 6f  t a temporary fo
37f20 6c 64 65 72 20 6f 6e 20 57 69 6e 64 6f 77 73 20  lder on Windows 
37f30 52 75 6e 74 69 6d 65 20 28 57 69 6e 52 54 29 2e  Runtime (WinRT).
37f40 0a 2a 2a 20 42 75 74 20 66 6f 72 20 61 6c 6c 20  .** But for all 
37f50 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 2c  other platforms,
37f60 20 69 74 20 69 73 20 68 69 67 68 6c 79 20 72 65   it is highly re
37f70 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
37f80 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 6e  pplications.** n
37f90 65 69 74 68 65 72 20 72 65 61 64 20 6e 6f 72 20  either read nor 
37fa0 77 72 69 74 65 20 74 68 69 73 20 76 61 72 69 61  write this varia
37fb0 62 6c 65 2e 20 20 54 68 69 73 20 67 6c 6f 62 61  ble.  This globa
37fc0 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20  l variable is a 
37fd0 72 65 6c 69 63 0a 2a 2a 20 74 68 61 74 20 65 78  relic.** that ex
37fe0 69 73 74 73 20 66 6f 72 20 62 61 63 6b 77 61 72  ists for backwar
37ff0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
38000 20 6f 66 20 6c 65 67 61 63 79 20 61 70 70 6c 69   of legacy appli
38010 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 68 6f 75  cations and shou
38020 6c 64 0a 2a 2a 20 62 65 20 61 76 6f 69 64 65 64  ld.** be avoided
38030 20 69 6e 20 6e 65 77 20 70 72 6f 6a 65 63 74 73   in new projects
38040 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ..**.** It is no
38050 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f  t safe to read o
38060 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  r modify this va
38070 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74  riable in more t
38080 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61  han one.** threa
38090 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74  d at a time.  It
380a0 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
380b0 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
380c0 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  his variable.** 
380d0 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  if a [database c
380e0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
380f0 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20  ing used at the 
38100 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73  same time in a s
38110 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61  eparate.** threa
38120 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65  d..** It is inte
38130 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76  nded that this v
38140 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f  ariable be set o
38150 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f  nce.** as part o
38160 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  f process initia
38170 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66  lization and bef
38180 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  ore any SQLite i
38190 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74  nterface.** rout
381a0 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63  ines have been c
381b0 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74  alled and that t
381c0 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d  his variable rem
381d0 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a  ain unchanged.**
381e0 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a   thereafter..**.
381f0 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74  ** ^The [temp_st
38200 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
38210 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79  agma] may modify
38220 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61   this variable a
38230 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74  nd cause.** it t
38240 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
38250 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
38260 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
38270 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c  .  ^Furthermore,
38280 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74  .** the [temp_st
38290 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
382a0 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73  agma] always ass
382b0 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74  umes that any st
382c0 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69  ring.** that thi
382d0 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74  s variable point
382e0 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20  s to is held in 
382f0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
38300 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
38310 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68  3_malloc] and th
38320 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74  e pragma may att
38330 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61  empt to free tha
38340 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e  t memory.** usin
38350 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d  g [sqlite3_free]
38360 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74  ..** Hence, if t
38370 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20  his variable is 
38380 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c  modified directl
38390 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f  y, either it sho
383a0 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e  uld be.** made N
383b0 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70  ULL or made to p
383c0 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f  oint to memory o
383d0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
383e0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a  lite3_malloc].**
383f0 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65   or else the use
38400 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74   of the [temp_st
38410 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
38420 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20  agma] should be 
38430 61 76 6f 69 64 65 64 2e 0a 2a 2a 20 45 78 63 65  avoided..** Exce
38440 70 74 20 77 68 65 6e 20 72 65 71 75 65 73 74 65  pt when requeste
38450 64 20 62 79 20 74 68 65 20 5b 74 65 6d 70 5f 73  d by the [temp_s
38460 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
38470 72 61 67 6d 61 5d 2c 20 53 51 4c 69 74 65 0a 2a  ragma], SQLite.*
38480 2a 20 64 6f 65 73 20 6e 6f 74 20 66 72 65 65 20  * does not free 
38490 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  the memory that 
384a0 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72  sqlite3_temp_dir
384b0 65 63 74 6f 72 79 20 70 6f 69 6e 74 73 20 74 6f  ectory points to
384c0 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 61 70 70  .  If.** the app
384d0 6c 69 63 61 74 69 6f 6e 20 77 61 6e 74 73 20 74  lication wants t
384e0 68 61 74 20 6d 65 6d 6f 72 79 20 74 6f 20 62 65  hat memory to be
384f0 20 66 72 65 65 64 2c 20 69 74 20 6d 75 73 74 20   freed, it must 
38500 64 6f 0a 2a 2a 20 73 6f 20 69 74 73 65 6c 66 2c  do.** so itself,
38510 20 74 61 6b 69 6e 67 20 63 61 72 65 20 74 6f 20   taking care to 
38520 6f 6e 6c 79 20 64 6f 20 73 6f 20 61 66 74 65 72  only do so after
38530 20 61 6c 6c 20 5b 64 61 74 61 62 61 73 65 20 63   all [database c
38540 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 6f 62  onnection].** ob
38550 6a 65 63 74 73 20 68 61 76 65 20 62 65 65 6e 20  jects have been 
38560 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a  destroyed..**.**
38570 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
38580 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72  ows Runtime user
38590 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70  s:</b>  The temp
385a0 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20  orary directory 
385b0 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70  must be set.** p
385c0 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20  rior to calling 
385d0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5d 20 6f  [sqlite3_open] o
385e0 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
385f0 76 32 5d 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  v2].  Otherwise,
38600 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74   various.** feat
38610 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72  ures that requir
38620 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d  e the use of tem
38630 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79  porary files may
38640 20 66 61 69 6c 2e 20 20 48 65 72 65 20 69 73 20   fail.  Here is 
38650 61 6e 0a 2a 2a 20 65 78 61 6d 70 6c 65 20 6f 66  an.** example of
38660 20 68 6f 77 20 74 6f 20 64 6f 20 74 68 69 73 20   how to do this 
38670 75 73 69 6e 67 20 43 2b 2b 20 77 69 74 68 20 74  using C++ with t
38680 68 65 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69  he Windows Runti
38690 6d 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  me:.**.** <block
386a0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 4c  quote><pre>.** L
386b0 50 43 57 53 54 52 20 7a 50 61 74 68 20 3d 20 57  PCWSTR zPath = W
386c0 69 6e 64 6f 77 73 3a 3a 53 74 6f 72 61 67 65 3a  indows::Storage:
386d0 3a 41 70 70 6c 69 63 61 74 69 6f 6e 44 61 74 61  :ApplicationData
386e0 3a 3a 43 75 72 72 65 6e 74 2d 3e 0a 2a 2a 20 26  ::Current->.** &
386f0 6e 62 73 70 3b 20 20 20 20 20 54 65 6d 70 6f 72  nbsp;     Tempor
38700 61 72 79 46 6f 6c 64 65 72 2d 3e 50 61 74 68 2d  aryFolder->Path-
38710 3e 44 61 74 61 28 29 3b 0a 2a 2a 20 63 68 61 72  >Data();.** char
38720 20 7a 50 61 74 68 42 75 66 26 23 39 31 3b 4d 41   zPathBuf&#91;MA
38730 58 5f 50 41 54 48 20 2b 20 31 26 23 39 33 3b 3b  X_PATH + 1&#93;;
38740 0a 2a 2a 20 6d 65 6d 73 65 74 28 7a 50 61 74 68  .** memset(zPath
38750 42 75 66 2c 20 30 2c 20 73 69 7a 65 6f 66 28 7a  Buf, 0, sizeof(z
38760 50 61 74 68 42 75 66 29 29 3b 0a 2a 2a 20 57 69  PathBuf));.** Wi
38770 64 65 43 68 61 72 54 6f 4d 75 6c 74 69 42 79 74  deCharToMultiByt
38780 65 28 43 50 5f 55 54 46 38 2c 20 30 2c 20 7a 50  e(CP_UTF8, 0, zP
38790 61 74 68 2c 20 2d 31 2c 20 7a 50 61 74 68 42 75  ath, -1, zPathBu
387a0 66 2c 20 73 69 7a 65 6f 66 28 7a 50 61 74 68 42  f, sizeof(zPathB
387b0 75 66 29 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20  uf),.** &nbsp;  
387c0 20 20 20 4e 55 4c 4c 2c 20 4e 55 4c 4c 29 3b 0a     NULL, NULL);.
387d0 2a 2a 20 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  ** sqlite3_temp_
387e0 64 69 72 65 63 74 6f 72 79 20 3d 20 73 71 6c 69  directory = sqli
387f0 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 25 73 22  te3_mprintf("%s"
38800 2c 20 7a 50 61 74 68 42 75 66 29 3b 0a 2a 2a 20  , zPathBuf);.** 
38810 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
38820 74 65 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  te>.*/.SQLITE_EX
38830 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74  TERN char *sqlit
38840 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
38850 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43