/ Hex Artifact Content
Login

Artifact b31477789bbb5bcbfcecf0afcb334240c41ea6a6:


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 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
61e0: 45 5f 4f 50 45 4e 5f 46 49 4c 45 50 52 4f 54 45  E_OPEN_FILEPROTE
61f0: 43 54 49 4f 4e 5f 4d 41 53 4b 20 20 20 20 20 20  CTION_MASK      
6200: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6210: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 37             0x007
6220: 30 30 30 30 30 0a 0a 2f 2a 20 52 65 73 65 72 76  00000../* Reserv
6230: 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20  ed:             
6240: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6250: 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  F00000 */../*.**
6260: 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63   CAPI3REF: Devic
6270: 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63  e Characteristic
6280: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76  s.**.** The xDev
6290: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
62a0: 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  cs method of the
62b0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
62c0: 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  hods].** object 
62d0: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
62e0: 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65  er which is a ve
62f0: 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a  ctor of these.**
6300: 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72   bit values expr
6310: 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61  essing I/O chara
6320: 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68  cteristics of th
6330: 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a  e mass storage.*
6340: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f  * device that ho
6350: 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61  lds the file tha
6360: 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  t the [sqlite3_i
6370: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65  o_methods].** re
6380: 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54  fers to..**.** 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 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
63b0: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
63c0: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
63d0: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
63e0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
63f0: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
6400: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
6410: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
6420: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
6430: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
6440: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
6450: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
6460: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
6470: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
6480: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
6490: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
64a0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
64b0: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
64c0: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
64d0: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
64e0: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
64f0: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
6500: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
6510: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
6520: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
6530: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
6540: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
6550: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
6560: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
6570: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
6580: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
6590: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
65a0: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
65b0: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
65c0: 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54  te().  The SQLIT
65d0: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
65e0: 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70  E_OVERWRITE prop
65f0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
6600: 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20  ** after reboot 
6610: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73  following a cras
6620: 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c  h or power loss,
6630: 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20   the only bytes 
6640: 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61  in a.** file tha
6650: 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61  t were written a
6660: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
6670: 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61  n level might ha
6680: 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e  ve changed.** an
6690: 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20  d that adjacent 
66a0: 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65  bytes, even byte
66b0: 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  s within the sam
66c0: 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20  e sector are.** 
66d0: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
66e0: 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
66f0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
6700: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
6710: 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69  PEN.** flag indi
6720: 63 61 74 65 20 74 68 61 74 20 61 20 66 69 6c 65  cate that a file
6730: 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74   cannot be delet
6740: 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54  ed when open.  T
6750: 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43  he.** SQLITE_IOC
6760: 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61  AP_IMMUTABLE fla
6770: 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74  g indicates that
6780: 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a   the file is on.
6790: 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64  ** read-only med
67a0: 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65  ia and cannot be
67b0: 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79   changed even by
67c0: 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a   processes with.
67d0: 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 76  ** elevated priv
67e0: 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69  ileges..*/.#defi
67f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6800: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20  ATOMIC          
6810: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6820: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
6830: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
6840: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6850: 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65  00000002.#define
6860: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6870: 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 20  OMIC1K          
6880: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a       0x00000004.
6890: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
68a0: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20  OCAP_ATOMIC2K   
68b0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
68c0: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
68d0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
68e0: 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC4K            
68f0: 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64     0x00000010.#d
6900: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6910: 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20  AP_ATOMIC8K     
6920: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6930: 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0020.#define SQL
6940: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6950: 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  16K             
6960: 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66   0x00000040.#def
6970: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6980: 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20  _ATOMIC32K      
6990: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
69a0: 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  80.#define SQLIT
69b0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
69c0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
69d0: 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e  x00000100.#defin
69e0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
69f0: 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20  AFE_APPEND      
6a00: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
6a10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6a20: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6a30: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6a40: 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20  0000400.#define 
6a50: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44  SQLITE_IOCAP_UND
6a60: 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50  ELETABLE_WHEN_OP
6a70: 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a 23  EN  0x00000800.#
6a80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6a90: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
6aa0: 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30 30  ERWRITE    0x000
6ab0: 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  01000.#define SQ
6ac0: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
6ad0: 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 20  ABLE            
6ae0: 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a    0x00002000../*
6af0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
6b00: 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c  le Locking Level
6b10: 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  s.**.** SQLite u
6b20: 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65  ses one of these
6b30: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
6b40: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
6b50: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
6b60: 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74  ls it makes to t
6b70: 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  he xLock() and x
6b80: 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73  Unlock() methods
6b90: 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  .** of an [sqlit
6ba0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
6bb0: 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e  bject..*/.#defin
6bc0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f  e SQLITE_LOCK_NO
6bd0: 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64  NE          0.#d
6be0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6bf0: 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20  K_SHARED        
6c00: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
6c10: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20  _LOCK_RESERVED  
6c20: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
6c30: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
6c40: 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  G       3.#defin
6c50: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58  e SQLITE_LOCK_EX
6c60: 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f  CLUSIVE     4../
6c70: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
6c80: 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54  ynchronization T
6c90: 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20  ype Flags.**.** 
6ca0: 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f  When SQLite invo
6cb0: 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20  kes the xSync() 
6cc0: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20  method of an.** 
6cd0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6ce0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75  ods] object it u
6cf0: 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f  ses a combinatio
6d00: 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e  n of.** these in
6d10: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
6d20: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
6d30: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ent..**.** When 
6d40: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
6d50: 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73  DATAONLY flag is
6d60: 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20   used, it means 
6d70: 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63  that the.** sync
6d80: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20   operation only 
6d90: 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64  needs to flush d
6da0: 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72  ata to mass stor
6db0: 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69  age.  Inode.** i
6dc0: 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20  nformation need 
6dd0: 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20  not be flushed. 
6de0: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
6df0: 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c  r bits of the fl
6e00: 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49  ag.** equal SQLI
6e10: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20  TE_SYNC_NORMAL, 
6e20: 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73  that means to us
6e30: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
6e40: 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49   semantics..** I
6e50: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72  f the lower four
6e60: 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49   bits equal SQLI
6e70: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68  TE_SYNC_FULL, th
6e80: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75  at means.** to u
6e90: 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c  se Mac OS X styl
6ea0: 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65  e fullsync inste
6eb0: 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a  ad of fsync()..*
6ec0: 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66  *.** Do not conf
6ed0: 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53  use the SQLITE_S
6ee0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
6ef0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
6f00: 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68  flags.** with th
6f10: 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  e [PRAGMA synchr
6f20: 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e  onous]=NORMAL an
6f30: 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  d [PRAGMA synchr
6f40: 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73  onous]=FULL.** s
6f50: 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73  ettings.  The [s
6f60: 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d  ynchronous pragm
6f70: 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68  a] determines wh
6f80: 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a  en calls to the.
6f90: 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74  ** xSync VFS met
6fa0: 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70  hod occur and ap
6fb0: 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20  plies uniformly 
6fc0: 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66  across all platf
6fd0: 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  orms..** The SQL
6fe0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
6ff0: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
7000: 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72  FULL flags deter
7010: 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72  mine how.** ener
7020: 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75  getic or rigorou
7030: 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68  s or forceful th
7040: 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e  e sync operation
7050: 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c  s are and.** onl
7060: 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65  y make a differe
7070: 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66  nce on Mac OSX f
7080: 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53  or the default S
7090: 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28  QLite code..** (
70a0: 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20  Third-party VFS 
70b0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
70c0: 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20  might also make 
70d0: 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a  the distinction.
70e0: 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54  ** between SQLIT
70f0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
7100: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
7110: 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68  LL, but among th
7120: 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73  e.** operating s
7130: 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20  ystems natively 
7140: 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
7150: 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53  ite, only Mac OS
7160: 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74  X.** cares about
7170: 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e   the difference.
7180: 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ).*/.#define SQL
7190: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
71a0: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23         0x00002.#
71b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
71c0: 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20  NC_FULL         
71d0: 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65   0x00003.#define
71e0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
71f0: 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30  AONLY      0x000
7200: 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  10../*.** CAPI3R
7210: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
7220: 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c   Open File Handl
7230: 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69  e.**.** An [sqli
7240: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
7250: 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f   represents an o
7260: 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20  pen file in the 
7270: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
7280: 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20   | OS interface 
7290: 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64  layer].  Individ
72a0: 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ual OS interface
72b0: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
72c0: 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74  ons will.** want
72d0: 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69   to subclass thi
72e0: 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65  s object by appe
72f0: 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c  nding additional
7300: 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74   fields.** for t
7310: 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54  heir own use.  T
7320: 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72  he pMethods entr
7330: 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  y is a pointer t
7340: 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  o an.** [sqlite3
7350: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
7360: 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
7370: 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72   methods for per
7380: 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f  forming.** I/O o
7390: 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65  perations on the
73a0: 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74   open file..*/.t
73b0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
73c0: 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74  lite3_file sqlit
73d0: 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20  e3_file;.struct 
73e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20  sqlite3_file {. 
73f0: 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71   const struct sq
7400: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7410: 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20   *pMethods;  /* 
7420: 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f  Methods for an o
7430: 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a  pen file */.};..
7440: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7450: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c  OS Interface Fil
7460: 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64  e Virtual Method
7470: 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45  s Object.**.** E
7480: 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64  very file opened
7490: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
74a0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
74b0: 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a  od populates an.
74c0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
74d0: 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f  ] object (or, mo
74e0: 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73  re commonly, a s
74f0: 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a  ubclass of the.*
7500: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
7510: 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20   object) with a 
7520: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
7530: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
7540: 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f  bject..** This o
7550: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
7560: 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74  e methods used t
7570: 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
7580: 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  s operations.** 
7590: 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e  against the open
75a0: 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65   file represente
75b0: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
75c0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a  3_file] object..
75d0: 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71  **.** If the [sq
75e0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
75f0: 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65   method sets the
7600: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
7610: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a  ethods element .
7620: 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ** to a non-NULL
7630: 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74   pointer, then t
7640: 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  he sqlite3_io_me
7650: 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74  thods.xClose met
7660: 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e  hod.** may be in
7670: 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68  voked even if th
7680: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7690: 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74  Open] reported t
76a0: 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20  hat it failed.  
76b0: 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20  The.** only way 
76c0: 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c  to prevent a cal
76d0: 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c  l to xClose foll
76e0: 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b  owing a failed [
76f0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7700: 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65  n].** is for the
7710: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
7720: 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20  pen] to set the 
7730: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
7740: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a  thods element.**
7750: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
7760: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
7770: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
7780: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
7790: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
77a0: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
77b0: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
77c0: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
77d0: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
77e0: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
77f0: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
7800: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
7810: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
7820: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
7830: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
7840: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
7850: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
7860: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
7870: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
7880: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
7890: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
78a0: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
78b0: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
78c0: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
78d0: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
78e0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
78f0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
7900: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7910: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
7920: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7930: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
7940: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7950: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
7960: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7970: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
7980: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
7990: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
79a0: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
79b0: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
79c0: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
79d0: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
79e0: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
79f0: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
7a00: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
7a10: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
7a20: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
7a30: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
7a40: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
7a50: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
7a60: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
7a70: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
7a80: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
7a90: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
7aa0: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
7ab0: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
7ac0: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
7ad0: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
7ae0: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
7af0: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
7b00: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
7b10: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
7b20: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
7b30: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
7b40: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
7b50: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7b60: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
7b70: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
7b80: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
7b90: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
7ba0: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
7bb0: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
7bc0: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
7bd0: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
7be0: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
7bf0: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
7c00: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
7c10: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
7c20: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
7c30: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
7c40: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
7c50: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
7c60: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
7c70: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
7c80: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
7c90: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
7ca0: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
7cb0: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
7cc0: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
7cd0: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
7ce0: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
7cf0: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
7d00: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
7d10: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
7d20: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
7d30: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
7d40: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
7d50: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
7d60: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
7d70: 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e  ..** A [file con
7d80: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c  trol opcodes | l
7d90: 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20  ist of opcodes] 
7da0: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73  less than 100 is
7db0: 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41   available..** A
7dc0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
7dd0: 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d   define a custom
7de0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
7df0: 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20  thod should use 
7e00: 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74  opcodes.** great
7e10: 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61  er than 100 to a
7e20: 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20  void conflicts. 
7e30: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
7e40: 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  ions should.** r
7e50: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f  eturn [SQLITE_NO
7e60: 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65  TFOUND] for file
7e70: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73   control opcodes
7e80: 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
7e90: 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a  t.** recognize..
7ea0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f  **.** The xSecto
7eb0: 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72  rSize() method r
7ec0: 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f  eturns the secto
7ed0: 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a  r size of the.**
7ee0: 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64   device that und
7ef0: 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e  erlies the file.
7f00: 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a    The sector siz
7f10: 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69  e is the.** mini
7f20: 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63  mum write that c
7f30: 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20  an be performed 
7f40: 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69  without disturbi
7f50: 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65  ng.** other byte
7f60: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  s in the file.  
7f70: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61  The xDeviceChara
7f80: 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20  cteristics().** 
7f90: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
7fa0: 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63   bit vector desc
7fb0: 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73  ribing behaviors
7fc0: 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72   of the.** under
7fd0: 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a  lying device:.**
7fe0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
7ff0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8000: 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  TOMIC].** <li> [
8010: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8020: 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC512].** <li> 
8030: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8040: 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC1K].** <li> 
8050: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8060: 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC2K].** <li> 
8070: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8080: 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC4K].** <li> 
8090: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
80a0: 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC8K].** <li> 
80b0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
80c0: 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC16K].** <li>
80d0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
80e0: 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC32K].** <li
80f0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8100: 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC64K].** <l
8110: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8120: 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a  _SAFE_APPEND].**
8130: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8140: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a  CAP_SEQUENTIAL].
8150: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** 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 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
8180: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
8190: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
81a0: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
81b0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
81c0: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
81d0: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
81e0: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
81f0: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
8200: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
8210: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
8220: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
8230: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
8240: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
8250: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
8260: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
8270: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
8280: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
8290: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
82a0: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
82b0: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
82c0: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
82d0: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
82e0: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
82f0: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
8300: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
8310: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
8320: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
8330: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
8340: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
8350: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
8360: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
8370: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
8380: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
8390: 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78  te()..**.** If x
83a0: 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53  Read() returns S
83b0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
83c0: 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 61  T_READ it must a
83d0: 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74  lso fill.** in t
83e0: 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f  he unread portio
83f0: 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ns of the buffer
8400: 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20   with zeros.  A 
8410: 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c  VFS that.** fail
8420: 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  s to zero-fill s
8430: 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 74  hort reads might
8440: 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20   seem to work.  
8450: 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c  However,.** fail
8460: 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ure to zero-fill
8470: 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c   short reads wil
8480: 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61  l eventually lea
8490: 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65  d to.** database
84a0: 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a   corruption..*/.
84b0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
84c0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
84d0: 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  s sqlite3_io_met
84e0: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
84f0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
8500: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
8510: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65  ;.  int (*xClose
8520: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8530: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29  ;.  int (*xRead)
8540: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8550: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
8560: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
8570: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
8580: 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66  Write)(sqlite3_f
8590: 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ile*, const void
85a0: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
85b0: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
85c0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e  );.  int (*xTrun
85d0: 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69  cate)(sqlite3_fi
85e0: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
85f0: 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20  64 size);.  int 
8600: 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33  (*xSync)(sqlite3
8610: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67  _file*, int flag
8620: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  s);.  int (*xFil
8630: 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66  eSize)(sqlite3_f
8640: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8650: 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69  t64 *pSize);.  i
8660: 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69  nt (*xLock)(sqli
8670: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
8680: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b  .  int (*xUnlock
8690: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
86a0: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
86b0: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63  CheckReservedLoc
86c0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
86d0: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
86e0: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f  .  int (*xFileCo
86f0: 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66  ntrol)(sqlite3_f
8700: 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f  ile*, int op, vo
8710: 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74  id *pArg);.  int
8720: 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28   (*xSectorSize)(
8730: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8740: 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43    int (*xDeviceC
8750: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28  haracteristics)(
8760: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8770: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f    /* Methods abo
8780: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72  ve are valid for
8790: 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20   version 1 */.  
87a0: 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73  int (*xShmMap)(s
87b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
87c0: 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c  t iPg, int pgsz,
87d0: 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74   int, void volat
87e0: 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  ile**);.  int (*
87f0: 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65  xShmLock)(sqlite
8800: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66  3_file*, int off
8810: 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20  set, int n, int 
8820: 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28  flags);.  void (
8830: 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73 71  *xShmBarrier)(sq
8840: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8850: 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29  int (*xShmUnmap)
8860: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8870: 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b  int deleteFlag);
8880: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
8890: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
88a0: 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20  r version 2 */. 
88b0: 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28 73   int (*xFetch)(s
88c0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
88d0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
88e0: 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69  t, int iAmt, voi
88f0: 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28  d **pp);.  int (
8900: 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74  *xUnfetch)(sqlit
8910: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
8920: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76  3_int64 iOfst, v
8930: 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65  oid *p);.  /* Me
8940: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
8950: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
8960: 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69  n 3 */.  /* Addi
8970: 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d  tional methods m
8980: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
8990: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a  uture releases *
89a0: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
89b0: 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46  3REF: Standard F
89c0: 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f  ile Control Opco
89d0: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
89e0: 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f   {file control o
89f0: 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63 6f  pcodes} {file co
8a00: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a  ntrol opcode}.**
8a10: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
8a20: 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  r constants are 
8a30: 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20  opcodes for the 
8a40: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
8a50: 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  hod.** of the [s
8a60: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
8a70: 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f  s] object and fo
8a80: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  r the [sqlite3_f
8a90: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a  ile_control()].*
8aa0: 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  * interface..**.
8ab0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
8ac0: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20  CNTL_LOCKSTATE] 
8ad0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
8ae0: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
8af0: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
8b00: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
8b10: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
8b20: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e  write the curren
8b30: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68  t state of.** th
8b40: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b  e lock (one of [
8b50: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
8b60: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
8b70: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c  SHARED],.** [SQL
8b80: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
8b90: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  D], [SQLITE_LOCK
8ba0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53  _PENDING], or [S
8bb0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
8bc0: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61  SIVE]).** into a
8bd0: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74  n integer that t
8be0: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
8bf0: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73   points to. This
8c00: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
8c10: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
8c20: 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e  sting and only n
8c30: 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f  eeds to be suppo
8c40: 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45  rted when SQLITE
8c50: 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69  _TEST.** is defi
8c60: 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  ned..** <ul>.** 
8c70: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
8c80: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a  TL_SIZE_HINT]].*
8c90: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
8ca0: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f  NTL_SIZE_HINT] o
8cb0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 62 79  pcode is used by
8cc0: 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20   SQLite to give 
8cd0: 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72  the VFS.** layer
8ce0: 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c   a hint of how l
8cf0: 61 72 67 65 20 74 68 65 20 64 61 74 61 62 61 73  arge the databas
8d00: 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77  e file will grow
8d10: 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68   to be during th
8d20: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61  e.** current tra
8d30: 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20  nsaction.  This 
8d40: 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72  hint is not guar
8d50: 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63 63  anteed to be acc
8d60: 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20  urate but it.** 
8d70: 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20  is often close. 
8d80: 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   The underlying 
8d90: 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65  VFS might choose
8da0: 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20   to preallocate 
8db0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
8dc0: 20 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20   space based on 
8dd0: 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64  this hint in ord
8de0: 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65  er to help write
8df0: 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  s to the databas
8e00: 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61  e.** file run fa
8e10: 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ster..**.** <li>
8e20: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  [[SQLITE_FCNTL_C
8e30: 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54  HUNK_SIZE]].** T
8e40: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
8e50: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63  _CHUNK_SIZE] opc
8e60: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 72  ode is used to r
8e70: 65 71 75 65 73 74 20 74 68 61 74 20 74 68 65 20  equest that the 
8e80: 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61  VFS.** extends a
8e90: 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 68 65  nd truncates the
8ea0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
8eb0: 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69  n chunks of a si
8ec0: 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ze specified.** 
8ed0: 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68 65  by the user. The
8ee0: 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
8ef0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   to [sqlite3_fil
8f00: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f  e_control()] sho
8f10: 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f  uld .** point to
8f20: 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70   an integer (typ
8f30: 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e  e int) containin
8f40: 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d  g the new chunk-
8f50: 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66  size to use.** f
8f60: 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64  or the nominated
8f70: 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63   database. Alloc
8f80: 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 66  ating database f
8f90: 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72  ile space in lar
8fa0: 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61  ge.** chunks (sa
8fb0: 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29  y 1MB at a time)
8fc0: 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c  , may reduce fil
8fd0: 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e  e-system fragmen
8fe0: 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d  tation and.** im
8ff0: 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63  prove performanc
9000: 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d  e on some system
9010: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  s..**.** <li>[[S
9020: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
9030: 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68  _POINTER]].** Th
9040: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9050: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70  FILE_POINTER] op
9060: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
9070: 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72  obtain a pointer
9080: 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
9090: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
90a0: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
90b0: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61   a particular da
90c0: 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
90d0: 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65 20 5b  tion.  See the [
90e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
90f0: 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74  trol()] document
9100: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64  ation for.** add
9110: 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
9120: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ion..**.** <li>[
9130: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
9140: 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20  NC_OMITTED]].** 
9150: 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65  No longer in use
9160: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9170: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d  LITE_FCNTL_SYNC]
9180: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
9190: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63  _FCNTL_SYNC] opc
91a0: 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64  ode is generated
91b0: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53   internally by S
91c0: 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e  QLite and.** sen
91d0: 74 20 74 6f 20 74 68 65 20 56 46 53 20 69 6d 6d  t to the VFS imm
91e0: 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20  ediately before 
91f0: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64  the xSync method
9200: 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61   is invoked on a
9210: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c  .** database fil
9220: 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20 4f 72  e descriptor. Or
9230: 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63 20 6d  , if the xSync m
9240: 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76  ethod is not inv
9250: 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75 73 65  oked .** because
9260: 20 74 68 65 20 75 73 65 72 20 68 61 73 20 63 6f   the user has co
9270: 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74 65 20  nfigured SQLite 
9280: 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41  with .** [PRAGMA
9290: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50   synchronous | P
92a0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
92b0: 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69 6e 76  s=OFF] it is inv
92c0: 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a  oked in place .*
92d0: 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63 20 6d  * of the xSync m
92e0: 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63  ethod. In most c
92f0: 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e 74 65  ases, the pointe
9300: 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  r argument passe
9310: 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73 20 66  d with.** this f
9320: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e  ile-control is N
9330: 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69 66  ULL. However, if
9340: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
9350: 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79 6e 63  le is being sync
9360: 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66  ed.** as part of
9370: 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62 61 73   a multi-databas
9380: 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72  e commit, the ar
9390: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f  gument points to
93a0: 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65   a nul-terminate
93b0: 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74  d.** string cont
93c0: 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61 6e 73  aining the trans
93d0: 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a  actions master-j
93e0: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65  ournal file name
93f0: 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a 2a 2a  . VFSes that .**
9400: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69   do not need thi
9410: 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20  s signal should 
9420: 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20  silently ignore 
9430: 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70  this opcode. App
9440: 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68  lications .** sh
9450: 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73  ould not call [s
9460: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9470: 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73  rol()] with this
9480: 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67   opcode as doing
9490: 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72   so may .** disr
94a0: 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f  upt the operatio
94b0: 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c  n of the special
94c0: 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74 20  ized VFSes that 
94d0: 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20  do require it.  
94e0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
94f0: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
9500: 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54  _PHASETWO]].** T
9510: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9520: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f  _COMMIT_PHASETWO
9530: 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65  ] opcode is gene
9540: 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  rated internally
9550: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e   by SQLite.** an
9560: 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46  d sent to the VF
9570: 53 20 61 66 74 65 72 20 61 20 74 72 61 6e 73 61  S after a transa
9580: 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e 20 63  ction has been c
9590: 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64 69 61  ommitted immedia
95a0: 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f  tely.** but befo
95b0: 72 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  re the database 
95c0: 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53  is unlocked. VFS
95d0: 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e  es that do not n
95e0: 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 0a  eed this signal.
95f0: 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74  ** should silent
9600: 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f  ly ignore this o
9610: 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69  pcode. Applicati
9620: 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63  ons should not c
9630: 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  all.** [sqlite3_
9640: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
9650: 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65  with this opcode
9660: 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79   as doing so may
9670: 20 64 69 73 72 75 70 74 20 74 68 65 20 0a 2a 2a   disrupt the .**
9680: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68   operation of th
9690: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46  e specialized VF
96a0: 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71 75  Ses that do requ
96b0: 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20  ire it.  .**.** 
96c0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
96d0: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52  TL_WIN32_AV_RETR
96e0: 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  Y]].** ^The [SQL
96f0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
9700: 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65  AV_RETRY] opcode
9710: 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66   is used to conf
9720: 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a  igure automatic.
9730: 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20  ** retry counts 
9740: 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f  and intervals fo
9750: 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49  r certain disk I
9760: 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f  /O operations fo
9770: 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73  r the.** windows
9780: 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20   [VFS] in order 
9790: 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73  to provide robus
97a0: 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72 65  tness in the pre
97b0: 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69  sence of.** anti
97c0: 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e  -virus programs.
97d0: 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68    By default, th
97e0: 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69  e windows VFS wi
97f0: 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72 65  ll retry file re
9800: 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74  ad,.** file writ
9810: 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65  e, and file dele
9820: 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70  te operations up
9830: 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69   to 10 times, wi
9840: 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66  th a delay.** of
9850: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
9860: 20 62 65 66 6f 72 65 20 74 68 65 20 66 69 72 73   before the firs
9870: 74 20 72 65 74 72 79 20 61 6e 64 20 77 69 74 68  t retry and with
9880: 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65   the delay incre
9890: 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61  asing.** by an a
98a0: 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c  dditional 25 mil
98b0: 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65  liseconds with e
98c0: 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 20 72  ach subsequent r
98d0: 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f  etry.  This.** o
98e0: 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65  pcode allows the
98f0: 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31  se two values (1
9900: 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 32 35  0 retries and 25
9910: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
9920: 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65   delay).** to be
9930: 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20   adjusted.  The 
9940: 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67  values are chang
9950: 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62  ed for all datab
9960: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a  ase connections.
9970: 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  ** within the sa
9980: 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65  me process.  The
9990: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
99a0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72  ointer to an arr
99b0: 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74  ay of two.** int
99c0: 65 67 65 72 73 20 77 68 65 72 65 20 74 68 65 20  egers where the 
99d0: 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 69 20  first integer i 
99e0: 74 68 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f  the new retry co
99f0: 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f  unt and the seco
9a00: 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73  nd.** integer is
9a10: 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20   the delay.  If 
9a20: 65 69 74 68 65 72 20 69 6e 74 65 67 65 72 20 69  either integer i
9a30: 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
9a40: 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20   the setting.** 
9a50: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62  is not changed b
9a60: 75 74 20 69 6e 73 74 65 61 64 20 74 68 65 20 70  ut instead the p
9a70: 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68  rior value of th
9a80: 61 74 20 73 65 74 74 69 6e 67 20 69 73 20 77 72  at setting is wr
9a90: 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68  itten.** into th
9aa0: 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61  e array entry, a
9ab0: 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72  llowing the curr
9ac0: 65 6e 74 20 72 65 74 72 79 20 73 65 74 74 69 6e  ent retry settin
9ad0: 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65  gs to be.** inte
9ae0: 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a  rrogated.  The z
9af0: 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  DbName parameter
9b00: 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a   is ignored..**.
9b10: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9b20: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41  FCNTL_PERSIST_WA
9b30: 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  L]].** ^The [SQL
9b40: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
9b50: 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73  T_WAL] opcode is
9b60: 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20   used to set or 
9b70: 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72  query the.** per
9b80: 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57  sistent [WAL | W
9b90: 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20  rite Ahead Log] 
9ba0: 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66  setting.  By def
9bb0: 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69  ault, the auxili
9bc0: 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65  ary.** write ahe
9bd0: 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65  ad log and share
9be0: 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75  d memory files u
9bf0: 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74  sed for transact
9c00: 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61  ion control.** a
9c10: 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  re automatically
9c20: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68   deleted when th
9c30: 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74  e latest connect
9c40: 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62  ion to the datab
9c50: 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20  ase.** closes.  
9c60: 53 65 74 74 69 6e 67 20 70 65 72 73 69 73 74 65  Setting persiste
9c70: 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73  nt WAL mode caus
9c80: 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74  es those files t
9c90: 6f 20 70 65 72 73 69 73 74 20 61 66 74 65 72 0a  o persist after.
9ca0: 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69  ** close.  Persi
9cb0: 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20  sting the files 
9cc0: 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f  is useful when o
9cd0: 74 68 65 72 20 70 72 6f 63 65 73 73 65 73 20 74  ther processes t
9ce0: 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61  hat do not.** ha
9cf0: 76 65 20 77 72 69 74 65 20 70 65 72 6d 69 73 73  ve write permiss
9d00: 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63  ion on the direc
9d10: 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20  tory containing 
9d20: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
9d30: 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61  e want.** to rea
9d40: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  d the database f
9d50: 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20  ile, as the WAL 
9d60: 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72  and shared memor
9d70: 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69  y files must exi
9d80: 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66  st.** in order f
9d90: 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
9da0: 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20  to be readable. 
9db0: 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
9dc0: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
9dd0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
9de0: 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70  l()] for this op
9df0: 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61  code should be a
9e00: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
9e10: 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20  nteger..** That 
9e20: 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20  integer is 0 to 
9e30: 64 69 73 61 62 6c 65 20 70 65 72 73 69 73 74 65  disable persiste
9e40: 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31  nt WAL mode or 1
9e50: 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69   to enable persi
9e60: 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64  stent.** WAL mod
9e70: 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67  e.  If the integ
9e80: 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69  er is -1, then i
9e90: 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e  t is overwritten
9ea0: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
9eb0: 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74  t.** WAL persist
9ec0: 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a  ence setting..**
9ed0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9ee0: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
9ef0: 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20  _OVERWRITE]].** 
9f00: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
9f10: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TL_POWERSAFE_OVE
9f20: 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69  RWRITE] opcode i
9f30: 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72  s used to set or
9f40: 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65   query the.** pe
9f50: 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73  rsistent "powers
9f60: 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f  afe-overwrite" o
9f70: 72 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67  r "PSOW" setting
9f80: 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65 74 74  .  The PSOW sett
9f90: 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65  ing.** determine
9fa0: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f  s the [SQLITE_IO
9fb0: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
9fc0: 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20  ERWRITE] bit of 
9fd0: 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68  the.** xDeviceCh
9fe0: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65  aracteristics me
9ff0: 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74  thods. The fourt
a000: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  h parameter to.*
a010: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
a020: 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74  control()] for t
a030: 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c  his opcode shoul
a040: 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  d be a pointer t
a050: 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  o an integer..**
a060: 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73   That integer is
a070: 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65   0 to disable ze
a080: 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f  ro-damage mode o
a090: 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65  r 1 to enable ze
a0a0: 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64  ro-damage.** mod
a0b0: 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67  e.  If the integ
a0c0: 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69  er is -1, then i
a0d0: 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e  t is overwritten
a0e0: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
a0f0: 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65  t.** zero-damage
a100: 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a   mode setting..*
a110: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
a120: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
a130: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
a140: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
a150: 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69  ITE] opcode is i
a160: 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65  nvoked by SQLite
a170: 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a   after opening.*
a180: 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e 73 61  * a write transa
a190: 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74  ction to indicat
a1a0: 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69  e that, unless i
a1b0: 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b  t is rolled back
a1c0: 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61   for some.** rea
a1d0: 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20  son, the entire 
a1e0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
a1f0: 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74 65  ll be overwritte
a200: 6e 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74  n by the current
a210: 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e   .** transaction
a220: 2e 20 54 68 69 73 20 69 73 20 75 73 65 64 20 62  . This is used b
a230: 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69  y VACUUM operati
a240: 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ons..**.** <li>[
a250: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
a260: 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  SNAME]].** ^The 
a270: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
a280: 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61  SNAME] opcode ca
a290: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
a2a0: 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
a2b0: 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20  .** all [VFSes] 
a2c0: 69 6e 20 74 68 65 20 56 46 53 20 73 74 61 63 6b  in the VFS stack
a2d0: 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65  .  The names are
a2e0: 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d   of all VFS shim
a2f0: 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e  s and the.** fin
a300: 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20  al bottom-level 
a310: 56 46 53 20 61 72 65 20 77 72 69 74 74 65 6e 20  VFS are written 
a320: 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
a330: 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73  ined from .** [s
a340: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
a350: 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20   and the result 
a360: 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65  is stored in the
a370: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a   char* variable.
a380: 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75 72  ** that the four
a390: 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  th parameter of 
a3a0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
a3b0: 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20  ntrol()] points 
a3c0: 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65  to..** The calle
a3d0: 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  r is responsible
a3e0: 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65   for freeing the
a3f0: 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e   memory when don
a400: 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61  e.  As with.** a
a410: 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  ll file-control 
a420: 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69  actions, there i
a430: 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74  s no guarantee t
a440: 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63  hat this will ac
a450: 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79  tually.** do any
a460: 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20  thing.  Callers 
a470: 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a  should initializ
a480: 65 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69  e the char* vari
a490: 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a  able to a NULL.*
a4a0: 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73  * pointer in cas
a4b0: 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74  e this file-cont
a4c0: 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65  rol is not imple
a4d0: 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69  mented.  This fi
a4e0: 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73  le-control.** is
a4f0: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69   intended for di
a500: 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c  agnostic use onl
a510: 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  y..**.** <li>[[S
a520: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
a530: 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65  MA]].** ^Wheneve
a540: 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61  r a [PRAGMA] sta
a550: 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64  tement is parsed
a560: 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e  , an [SQLITE_FCN
a570: 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66  TL_PRAGMA] .** f
a580: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73  ile control is s
a590: 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20  ent to the open 
a5a0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
a5b0: 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64  bject correspond
a5c0: 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61  ing.** to the da
a5d0: 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77  tabase file to w
a5e0: 68 69 63 68 20 74 68 65 20 70 72 61 67 6d 61 20  hich the pragma 
a5f0: 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73  statement refers
a600: 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a  . ^The argument.
a610: 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54  ** to the [SQLIT
a620: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
a630: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
a640: 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70  an array of.** p
a650: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
a660: 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77  gs (char**) in w
a670: 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20  hich the second 
a680: 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61  element of the a
a690: 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e  rray.** is the n
a6a0: 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d  ame of the pragm
a6b0: 61 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20  a and the third 
a6c0: 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61  element is the a
a6d0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a  rgument to the.*
a6e0: 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c  * pragma or NULL
a6f0: 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 68   if the pragma h
a700: 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20  as no argument. 
a710: 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f   ^The handler fo
a720: 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  r an.** [SQLITE_
a730: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
a740: 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f  le control can o
a750: 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74  ptionally make t
a760: 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74  he first element
a770: 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a  .** of the char*
a780: 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  * argument point
a790: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74   to a string obt
a7a0: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
a7b0: 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a  te3_mprintf()].*
a7c0: 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c  * or the equival
a7d0: 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74 72  ent and that str
a7e0: 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20  ing will become 
a7f0: 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68  the result of th
a800: 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74  e pragma or.** t
a810: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
a820: 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 66   if the pragma f
a830: 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a  ails. ^If the.**
a840: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
a850: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
a860: 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  rol returns [SQL
a870: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74  ITE_NOTFOUND], t
a880: 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b  hen normal .** [
a890: 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69  PRAGMA] processi
a8a0: 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e  ng continues.  ^
a8b0: 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  If the [SQLITE_F
a8c0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20  CNTL_PRAGMA].** 
a8d0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
a8e0: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
a8f0: 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72 73 65  , then the parse
a900: 72 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  r assumes that t
a910: 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61  he.** VFS has ha
a920: 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41  ndled the PRAGMA
a930: 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20   itself and the 
a940: 70 61 72 73 65 72 20 67 65 6e 65 72 61 74 65 73  parser generates
a950: 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70   a no-op.** prep
a960: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2e 20  ared statement. 
a970: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
a980: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
a990: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
a9a0: 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c  rns.** any resul
a9b0: 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61  t code other tha
a9c0: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72  n [SQLITE_OK] or
a9d0: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
a9e0: 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a  D], that means.*
a9f0: 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65  * that the VFS e
aa00: 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72  ncountered an er
aa10: 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69  ror while handli
aa20: 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20  ng the [PRAGMA] 
aa30: 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69  and the.** compi
aa40: 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52  lation of the PR
aa50: 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20  AGMA fails with 
aa60: 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20  an error.  ^The 
aa70: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
aa80: 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f  AGMA].** file co
aa90: 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20  ntrol occurs at 
aaa0: 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
aab0: 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e   pragma statemen
aac0: 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73  t analysis and s
aad0: 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20  o.** it is able 
aae0: 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c  to override buil
aaf0: 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74  t-in [PRAGMA] st
ab00: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
ab10: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
ab20: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d  TL_BUSYHANDLER]]
ab30: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
ab40: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
ab50: 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74  ER].** file-cont
ab60: 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  rol may be invok
ab70: 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20  ed by SQLite on 
ab80: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
ab90: 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72  e handle.** shor
aba0: 74 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 20  tly after it is 
abb0: 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20  opened in order 
abc0: 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 73  to provide a cus
abd0: 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 63  tom VFS with acc
abe0: 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f  ess.** to the co
abf0: 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68  nnections busy-h
ac00: 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  andler callback.
ac10: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
ac20: 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a   of type (void *
ac30: 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79  *).** - an array
ac40: 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29   of two (void *)
ac50: 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72   values. The fir
ac60: 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75  st (void *) actu
ac70: 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74  ally points.** t
ac80: 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20  o a function of 
ac90: 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f  type (int (*)(vo
aca0: 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72  id *)). In order
acb0: 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63   to invoke the c
acc0: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75  onnections.** bu
acd0: 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73  sy-handler, this
ace0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64   function should
acf0: 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
ad00: 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69   the second (voi
ad10: 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61  d *) in.** the a
ad20: 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79  rray as the only
ad30: 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74   argument. If it
ad40: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
ad50: 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72  o, then the oper
ad60: 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
ad70: 62 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 69  be retried. If i
ad80: 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20  t returns zero, 
ad90: 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73  the custom VFS s
ada0: 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68  hould abandon th
adb0: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65  e.** current ope
adc0: 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ration..**.** <l
add0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
ade0: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a  _TEMPFILENAME]].
adf0: 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20  ** ^Application 
ae00: 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b  can invoke the [
ae10: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d  SQLITE_FCNTL_TEM
ae20: 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d  PFILENAME] file-
ae30: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61  control.** to ha
ae40: 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61  ve SQLite genera
ae50: 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  te a.** temporar
ae60: 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67  y filename using
ae70: 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69   the same algori
ae80: 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c  thm that is foll
ae90: 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65  owed to generate
aea0: 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69  .** temporary fi
aeb0: 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50  lenames for TEMP
aec0: 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65   tables and othe
aed0: 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e  r internal uses.
aee0: 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e    The.** argumen
aef0: 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68  t should be a ch
af00: 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20  ar** which will 
af10: 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  be filled with t
af20: 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77  he filename.** w
af30: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
af40: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
af50: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
af60: 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72  ()].  The caller
af70: 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b   should.** invok
af80: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  e [sqlite3_free(
af90: 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74  )] on the result
afa0: 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f   to avoid a memo
afb0: 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c  ry leak..**.** <
afc0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
afd0: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a  L_MMAP_SIZE]].**
afe0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
aff0: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69  TL_MMAP_SIZE] fi
b000: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73  le control is us
b010: 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73  ed to query or s
b020: 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75  et the.** maximu
b030: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  m number of byte
b040: 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75  s that will be u
b050: 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d  sed for memory-m
b060: 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68  apped I/O..** Th
b070: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
b080: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c  pointer to a val
b090: 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74  ue of type sqlit
b0a0: 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a  e3_int64 that.**
b0b0: 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20   is an advisory 
b0c0: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
b0d0: 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66  f bytes in the f
b0e0: 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61  ile to memory ma
b0f0: 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74  p.  The.** point
b100: 65 72 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  er is overwritte
b110: 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76  n with the old v
b120: 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74  alue.  The limit
b130: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20   is not changed 
b140: 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  if.** the value 
b150: 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74  originally point
b160: 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76  ed to is negativ
b170: 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75  e, and so the cu
b180: 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20  rrent limit .** 
b190: 63 61 6e 20 62 65 20 71 75 65 72 69 65 64 20 62  can be queried b
b1a0: 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70  y passing in a p
b1b0: 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61  ointer to a nega
b1c0: 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68  tive number.  Th
b1d0: 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72  is.** file-contr
b1e0: 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  ol is used inter
b1f0: 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65  nally to impleme
b200: 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f  nt [PRAGMA mmap_
b210: 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  size]..**.** <li
b220: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b230: 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  TRACE]].** The [
b240: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
b250: 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  CE] file control
b260: 20 70 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f   provides adviso
b270: 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ry information.*
b280: 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f  * to the VFS abo
b290: 75 74 20 77 68 61 74 20 74 68 65 20 68 69 67 68  ut what the high
b2a0: 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65  er layers of the
b2b0: 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72   SQLite stack ar
b2c0: 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73  e doing..** This
b2d0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
b2e0: 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46   used by some VF
b2f0: 53 20 61 63 74 69 76 69 74 79 20 74 72 61 63 69  S activity traci
b300: 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54  ng [shims]..** T
b310: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
b320: 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
b330: 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72   string.  Higher
b340: 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a   layers in the.*
b350: 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d  * SQLite stack m
b360: 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74  ay generate inst
b370: 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66 69  ances of this fi
b380: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a  le control if.**
b390: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45   the [SQLITE_USE
b3a0: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f  _FCNTL_TRACE] co
b3b0: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
b3c0: 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  n is enabled..**
b3d0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b3e0: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44  _FCNTL_HAS_MOVED
b3f0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
b400: 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45  E_FCNTL_HAS_MOVE
b410: 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  D] file control 
b420: 69 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 61  interprets its a
b430: 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20  rgument as a.** 
b440: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
b450: 74 65 67 65 72 20 61 6e 64 20 69 74 20 77 72 69  teger and it wri
b460: 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e  tes a boolean in
b470: 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20  to that integer 
b480: 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20  depending.** on 
b490: 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
b4a0: 68 65 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e  he file has been
b4b0: 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c   renamed, moved,
b4c0: 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63   or deleted sinc
b4d0: 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73  e it.** was firs
b4e0: 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  t opened..**.** 
b4f0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b500: 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e  TL_WIN32_SET_HAN
b510: 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  DLE]].** The [SQ
b520: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
b530: 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63  _SET_HANDLE] opc
b540: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ode is used for 
b550: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73  debugging.  This
b560: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65  .** opcode cause
b570: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  s the xFileContr
b580: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61  ol method to swa
b590: 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c  p the file handl
b5a0: 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a  e with the one.*
b5b0: 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
b5c0: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  the pArg argumen
b5d0: 74 2e 20 20 54 68 69 73 20 63 61 70 61 62 69 6c  t.  This capabil
b5e0: 69 74 79 20 69 73 20 75 73 65 64 20 64 75 72 69  ity is used duri
b5f0: 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e  ng testing.** an
b600: 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  d only needs to 
b610: 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65  be supported whe
b620: 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73  n SQLITE_TEST is
b630: 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20   defined..**.** 
b640: 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </ul>.*/.#define
b650: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
b660: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20  CKSTATE         
b670: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
b680: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54  SQLITE_FCNTL_GET
b690: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
b6a0: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
b6b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f  QLITE_FCNTL_SET_
b6c0: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
b6d0: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
b6e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f  LITE_FCNTL_LAST_
b6f0: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20  ERRNO           
b700: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
b710: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
b720: 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20  INT             
b730: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
b740: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
b750: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  IZE             
b760: 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
b770: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
b780: 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20  NTER            
b790: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
b7a0: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
b7b0: 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38  TED            8
b7c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b7d0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
b7e0: 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a  ETRY          9.
b7f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b800: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
b810: 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
b820: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b830: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20  NTL_OVERWRITE   
b840: 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64             11.#d
b850: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b860: 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20  TL_VFSNAME      
b870: 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65            12.#de
b880: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b890: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
b8a0: 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66  WRITE    13.#def
b8b0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b8c0: 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
b8d0: 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 69          14.#defi
b8e0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b8f0: 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20  BUSYHANDLER     
b900: 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e         15.#defin
b910: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  e SQLITE_FCNTL_T
b920: 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20  EMPFILENAME     
b930: 20 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65        16.#define
b940: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d   SQLITE_FCNTL_MM
b950: 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20  AP_SIZE         
b960: 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20       18.#define 
b970: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
b980: 43 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CE              
b990: 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53      19.#define S
b9a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f  QLITE_FCNTL_HAS_
b9b0: 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20 20 20  MOVED           
b9c0: 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51     20.#define SQ
b9d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20  LITE_FCNTL_SYNC 
b9e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
b9f0: 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    21.#define SQL
ba00: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
ba10: 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20 20 20  _PHASETWO       
ba20: 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   22.#define SQLI
ba30: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
ba40: 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20  ET_HANDLE       
ba50: 32 33 0a 2f 2a 20 64 65 70 72 65 63 61 74 65 64  23./* deprecated
ba60: 20 6e 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e   names */.#defin
ba70: 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43  e SQLITE_GET_LOC
ba80: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
ba90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54  SQLITE_FCNTL_GET
baa0: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23  _LOCKPROXYFILE.#
bab0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
bac0: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
bad0: 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54       SQLITE_FCNT
bae0: 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  L_SET_LOCKPROXYF
baf0: 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  ILE.#define SQLI
bb00: 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20  TE_LAST_ERRNO   
bb10: 20 20 20 20 20 20 20 20 20 20 53 51 4c 49 54 45            SQLITE
bb20: 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e  _FCNTL_LAST_ERRN
bb30: 4f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  O../*.** CAPI3RE
bb40: 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a  F: Mutex Handle.
bb50: 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20  **.** The mutex 
bb60: 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51  module within SQ
bb70: 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71  Lite defines [sq
bb80: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20  lite3_mutex] to 
bb90: 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63  be an.** abstrac
bba0: 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74  t type for a mut
bbb0: 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  ex object.  The 
bbc0: 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65  SQLite core neve
bbd0: 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68  r looks.** at th
bbe0: 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
bbf0: 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  sentation of an 
bc00: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e  [sqlite3_mutex].
bc10: 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61    It only.** dea
bc20: 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73  ls with pointers
bc30: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
bc40: 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a  _mutex] object..
bc50: 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72  **.** Mutexes ar
bc60: 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  e created using 
bc70: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
bc80: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  lloc()]..*/.type
bc90: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
bca0: 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33  e3_mutex sqlite3
bcb0: 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _mutex;../*.** C
bcc0: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
bcd0: 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a  rface Object.**.
bce0: 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
bcf0: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
bd00: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
bd10: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
bd20: 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51  etween.** the SQ
bd30: 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68  Lite core and th
bd40: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65  e underlying ope
bd50: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
bd60: 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20  The "vfs".** in 
bd70: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
bd80: 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f  object stands fo
bd90: 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20  r "virtual file 
bda0: 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a  system".  See.**
bdb0: 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20   the [VFS | VFS 
bdc0: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
bdd0: 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72  or further infor
bde0: 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
bdf0: 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69  e value of the i
be00: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73  Version field is
be10: 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74   initially 1 but
be20: 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69   may be larger i
be30: 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73  n.** future vers
be40: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ions of SQLite. 
be50: 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   Additional fiel
be60: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
be70: 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62  ed to this.** ob
be80: 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56  ject when the iV
be90: 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20  ersion value is 
bea0: 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65  increased.  Note
beb0: 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74   that the struct
bec0: 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  ure.** of the sq
bed0: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
bee0: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
bef0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77  transaction betw
bf00: 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  een.** SQLite ve
bf10: 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20  rsion 3.5.9 and 
bf20: 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68  3.6.0 and yet th
bf30: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64  e iVersion field
bf40: 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69   was not.** modi
bf50: 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fied..**.** The 
bf60: 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69  szOsFile field i
bf70: 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
bf80: 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71  e subclassed [sq
bf90: 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73  lite3_file].** s
bfa0: 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79  tructure used by
bfb0: 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61   this VFS.  mxPa
bfc0: 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61  thname is the ma
bfd0: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a  ximum length of.
bfe0: 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e  ** a pathname in
bff0: 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a   this VFS..**.**
c000: 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69   Registered sqli
c010: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20  te3_vfs objects 
c020: 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69  are kept on a li
c030: 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64  nked list formed
c040: 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74   by.** the pNext
c050: 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b   pointer.  The [
c060: 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69  sqlite3_vfs_regi
c070: 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  ster()].** and [
c080: 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
c090: 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66  gister()] interf
c0a0: 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73  aces manage this
c0b0: 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68   list.** in a th
c0c0: 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20  read-safe way.  
c0d0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
c0e0: 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61  _find()] interfa
c0f0: 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74  ce.** searches t
c100: 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65  he list.  Neithe
c110: 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
c120: 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56  n code nor the V
c130: 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  FS.** implementa
c140: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20  tion should use 
c150: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
c160: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65  r..**.** The pNe
c170: 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  xt field is the 
c180: 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68  only field in th
c190: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
c1a0: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
c1b0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72  SQLite will ever
c1c0: 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65   modify.  SQLite
c1d0: 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73   will only acces
c1e0: 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74  s.** or modify t
c1f0: 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20  his field while 
c200: 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63  holding a partic
c210: 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65  ular static mute
c220: 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  x..** The applic
c230: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76  ation should nev
c240: 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69  er modify anythi
c250: 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71  ng within the sq
c260: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a  lite3_vfs.** obj
c270: 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a  ect once the obj
c280: 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67  ect has been reg
c290: 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  istered..**.** T
c2a0: 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68  he zName field h
c2b0: 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  olds the name of
c2c0: 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e   the VFS module.
c2d0: 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a    The name must.
c2e0: 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72  ** be unique acr
c2f0: 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75  oss all VFS modu
c300: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  les..**.** [[sql
c310: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d  ite3_vfs.xOpen]]
c320: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72  .** ^SQLite guar
c330: 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
c340: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
c350: 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20  ter to xOpen.** 
c360: 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  is either a NULL
c370: 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69   pointer or stri
c380: 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ng obtained.** f
c390: 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  rom xFullPathnam
c3a0: 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69  e() with an opti
c3b0: 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65  onal suffix adde
c3c0: 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66  d..** ^If a suff
c3d0: 69 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74  ix is added to t
c3e0: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
c3f0: 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a  ameter, it will.
c400: 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20  ** consist of a 
c410: 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61  single "-" chara
c420: 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79  cter followed by
c430: 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a   no more than.**
c440: 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   11 alphanumeric
c450: 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72   and/or "-" char
c460: 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69  acters..** ^SQLi
c470: 74 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61  te further guara
c480: 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  ntees that.** th
c490: 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  e string will be
c4a0: 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61   valid and uncha
c4b0: 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73  nged until xClos
c4c0: 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64  e() is.** called
c4d0: 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65  . Because of the
c4e0: 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
c4f0: 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ce,.** the [sqli
c500: 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61  te3_file] can sa
c510: 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69  fely store a poi
c520: 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66  nter to the.** f
c530: 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65  ilename if it ne
c540: 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  eds to remember 
c550: 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72  the filename for
c560: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a   some reason..**
c570: 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   If the zFilenam
c580: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
c590: 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70  Open is a NULL p
c5a0: 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65  ointer then xOpe
c5b0: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74  n.** must invent
c5c0: 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61   its own tempora
c5d0: 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20  ry name for the 
c5e0: 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72  file.  ^Whenever
c5f0: 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61   the .** xFilena
c600: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  me parameter is 
c610: 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73  NULL it will als
c620: 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  o be the case th
c630: 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20  at the.** flags 
c640: 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69  parameter will i
c650: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
c660: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
c670: 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  E]..**.** The fl
c680: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
c690: 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73  xOpen() includes
c6a0: 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e   all bits set in
c6b0: 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72  .** the flags ar
c6c0: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
c6d0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20  e3_open_v2()].  
c6e0: 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f  Or if [sqlite3_o
c6f0: 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  pen()].** or [sq
c700: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
c710: 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c  is used, then fl
c720: 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20  ags includes at 
c730: 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45  least.** [SQLITE
c740: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
c750: 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
c760: 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20  CREATE]. .** If 
c770: 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20  xOpen() opens a 
c780: 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74  file read-only t
c790: 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75  hen it sets *pOu
c7a0: 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63  tFlags to.** inc
c7b0: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
c7c0: 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74  N_READONLY].  Ot
c7d0: 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75  her bits in *pOu
c7e0: 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65  tFlags may be se
c7f0: 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74  t..**.** ^(SQLit
c800: 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20  e will also add 
c810: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
c820: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
c830: 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c  e xOpen().** cal
c840: 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  l, depending on 
c850: 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67  the object being
c860: 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c   opened:.**.** <
c870: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  ul>.** <li>  [SQ
c880: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
c890: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
c8a0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
c8b0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
c8c0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
c8d0: 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  P_DB].** <li>  [
c8e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
c8f0: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
c900: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
c910: 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a  TRANSIENT_DB].**
c920: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
c930: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a  PEN_SUBJOURNAL].
c940: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
c950: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
c960: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
c970: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d  SQLITE_OPEN_WAL]
c980: 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
c990: 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69  * The file I/O i
c9a0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61  mplementation ca
c9b0: 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74  n use the object
c9c0: 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a   type flags to.*
c9d0: 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79  * change the way
c9e0: 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66   it deals with f
c9f0: 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70  iles.  For examp
ca00: 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
ca10: 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20  on.** that does 
ca20: 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63  not care about c
ca30: 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72  rash recovery or
ca40: 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   rollback might 
ca50: 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e  make.** the open
ca60: 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69   of a journal fi
ca70: 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69  le a no-op.  Wri
ca80: 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72  tes to this jour
ca90: 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73  nal would.** als
caa0: 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64  o be no-ops, and
cab0: 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   any attempt to 
cac0: 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c  read the journal
cad0: 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a   would return.**
cae0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20   SQLITE_IOERR.  
caf0: 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  Or the implement
cb00: 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f  ation might reco
cb10: 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74  gnize that a dat
cb20: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69  abase.** file wi
cb30: 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65  ll be doing page
cb40: 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20  -aligned sector 
cb50: 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73  reads and writes
cb60: 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20   in a random.** 
cb70: 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70  order and set up
cb80: 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74   its I/O subsyst
cb90: 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a  em accordingly..
cba0: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67  **.** SQLite mig
cbb0: 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ht also add one 
cbc0: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
cbd0: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
cbe0: 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  pen method:.**.*
cbf0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
cc00: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
cc10: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c  TEONCLOSE].** <l
cc20: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
cc30: 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f  EXCLUSIVE].** </
cc40: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ul>.**.** The [S
cc50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
cc60: 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d  EONCLOSE] flag m
cc70: 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68  eans the file sh
cc80: 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74  ould be.** delet
cc90: 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c  ed when it is cl
cca0: 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c  osed.  ^The [SQL
ccb0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
ccc0: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20  NCLOSE].** will 
ccd0: 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20  be set for TEMP 
cce0: 64 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68  databases and th
ccf0: 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72  eir journals, tr
cd00: 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62  ansient.** datab
cd10: 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75  ases, and subjou
cd20: 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rnals..**.** ^Th
cd30: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  e [SQLITE_OPEN_E
cd40: 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69  XCLUSIVE] flag i
cd50: 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e  s always used in
cd60: 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20   conjunction.** 
cd70: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
cd80: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c  _OPEN_CREATE] fl
cd90: 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f  ag, which are bo
cda0: 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61  th directly.** a
cdb0: 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20  nalogous to the 
cdc0: 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45  O_EXCL and O_CRE
cdd0: 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20  AT flags of the 
cde0: 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20  POSIX open().** 
cdf0: 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45  API.  The SQLITE
ce00: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
ce10: 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65  flag, when paire
ce20: 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53  d with the .** S
ce30: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
ce40: 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e  E, is used to in
ce50: 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65  dicate that file
ce60: 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a   should always.*
ce70: 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e  * be created, an
ce80: 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20  d that it is an 
ce90: 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65  error if it alre
cea0: 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49  ady exists..** I
ceb0: 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20  t is <i>not</i> 
cec0: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
ced0: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
cee0: 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66   be opened .** f
cef0: 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63  or exclusive acc
cf00: 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c  ess..**.** ^At l
cf10: 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79  east szOsFile by
cf20: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72  tes of memory ar
cf30: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53  e allocated by S
cf40: 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64  QLite.** to hold
cf50: 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66   the  [sqlite3_f
cf60: 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70  ile] structure p
cf70: 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69  assed as the thi
cf80: 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  rd.** argument t
cf90: 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f  o xOpen.  The xO
cfa0: 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20  pen method does 
cfb0: 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61  not have to.** a
cfc0: 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75  llocate the stru
cfd0: 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64  cture; it should
cfe0: 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e   just fill it in
cff0: 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20  .  Note that.** 
d000: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
d010: 20 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71   must set the sq
d020: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
d030: 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a  ods to either.**
d040: 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65   a valid [sqlite
d050: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
d060: 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e  ject or to NULL.
d070: 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a    xOpen must do.
d080: 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20  ** this even if 
d090: 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20  the open fails. 
d0a0: 20 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20   SQLite expects 
d0b0: 74 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33  that the sqlite3
d0c0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a  _file.pMethods.*
d0d0: 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62  * element will b
d0e0: 65 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f  e valid after xO
d0f0: 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61  pen returns rega
d100: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75  rdless of the su
d110: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c  ccess.** or fail
d120: 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e  ure of the xOpen
d130: 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73   call..**.** [[s
d140: 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65  qlite3_vfs.xAcce
d150: 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61  ss]].** ^The fla
d160: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
d170: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
d180: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
d190: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73  XISTS].** to tes
d1a0: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65  t for the existe
d1b0: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f  nce of a file, o
d1c0: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
d1d0: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a  _READWRITE] to.*
d1e0: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  * test whether a
d1f0: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
d200: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
d210: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
d220: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
d230: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
d240: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65  e is at least re
d250: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69  adable.   The fi
d260: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
d270: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
d280: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77  ^SQLite will alw
d290: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20  ays allocate at 
d2a0: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65  least mxPathname
d2b0: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65  +1 bytes for the
d2c0: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65  .** output buffe
d2d0: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e  r xFullPathname.
d2e0: 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65    The exact size
d2f0: 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   of the output b
d300: 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f  uffer.** is also
d310: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72   passed as a par
d320: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20  ameter to both  
d330: 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20  methods. If the 
d340: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
d350: 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e   is not large en
d360: 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41  ough, [SQLITE_CA
d370: 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62  NTOPEN] should b
d380: 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63  e returned. Sinc
d390: 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e  e this is.** han
d3a0: 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20  dled as a fatal 
d3b0: 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c  error by SQLite,
d3c0: 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   vfs implementat
d3d0: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65  ions should ende
d3e0: 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65  avor.** to preve
d3f0: 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69  nt this by setti
d400: 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f  ng mxPathname to
d410: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20   a sufficiently 
d420: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a  large value..**.
d430: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
d440: 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20  ss(), xSleep(), 
d450: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20  xCurrentTime(), 
d460: 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65  and xCurrentTime
d470: 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72  Int64().** inter
d480: 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74  faces are not st
d490: 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66  rictly a part of
d4a0: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c   the filesystem,
d4b0: 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a   but they are.**
d4c0: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
d4d0: 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66   VFS structure f
d4e0: 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e  or completeness.
d4f0: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
d500: 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61  ess() function a
d510: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72  ttempts to retur
d520: 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a  n nBytes bytes.*
d530: 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74  * of good-qualit
d540: 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  y randomness int
d550: 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74  o zOut.  The ret
d560: 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  urn value is.** 
d570: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65  the actual numbe
d580: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61  r of bytes of ra
d590: 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
d5a0: 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70  d..** The xSleep
d5b0: 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73  () method causes
d5c0: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72   the calling thr
d5d0: 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72  ead to sleep for
d5e0: 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65   at.** least the
d5f0: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f   number of micro
d600: 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20  seconds given.  
d610: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
d620: 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  e().** method re
d630: 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44  turns a Julian D
d640: 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68  ay Number for th
d650: 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61  e current date a
d660: 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20  nd time as.** a 
d670: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
d680: 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43  alue..** ^The xC
d690: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
d6a0: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
d6b0: 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c  , as an integer,
d6c0: 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44   the Julian.** D
d6d0: 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70  ay Number multip
d6e0: 6c 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30  lied by 86400000
d6f0: 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   (the number of 
d700: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20  milliseconds in 
d710: 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61  .** a 24-hour da
d720: 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65  y).  .** ^SQLite
d730: 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43   will use the xC
d740: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
d750: 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20  ) method to get 
d760: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64  the current.** d
d770: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20  ate and time if 
d780: 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61  that method is a
d790: 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65  vailable (if iVe
d7a0: 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a  rsion is 2 or .*
d7b0: 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68  * greater and th
d7c0: 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  e function point
d7d0: 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20  er is not NULL) 
d7e0: 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61  and will fall ba
d7f0: 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e  ck.** to xCurren
d800: 74 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72  tTime() if xCurr
d810: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69  entTimeInt64() i
d820: 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a  s unavailable..*
d830: 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79  *.** ^The xSetSy
d840: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74  stemCall(), xGet
d850: 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e  SystemCall(), an
d860: 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c  d xNestSystemCal
d870: 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  l() interfaces.*
d880: 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62  * are not used b
d890: 79 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  y the SQLite cor
d8a0: 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e  e.  These option
d8b0: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
d8c0: 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79  e provided.** by
d8d0: 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66   some VFSes to f
d8e0: 61 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e  acilitate testin
d8f0: 67 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64  g of the VFS cod
d900: 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67  e. By overriding
d910: 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c   .** system call
d920: 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73  s with functions
d930: 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72   under its contr
d940: 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72  ol, a test progr
d950: 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61  am can.** simula
d960: 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72  te faults and er
d970: 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74  ror conditions t
d980: 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77  hat would otherw
d990: 69 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74  ise be difficult
d9a0: 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c  .** or impossibl
d9b0: 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68  e to induce.  Th
d9c0: 65 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20  e set of system 
d9d0: 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62  calls that can b
d9e0: 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20  e overridden.** 
d9f0: 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20  varies from one 
da00: 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20  VFS to another, 
da10: 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72  and from one ver
da20: 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65  sion of the same
da30: 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e   VFS to the.** n
da40: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
da50: 6e 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73  ns that use thes
da60: 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73  e interfaces mus
da70: 74 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f  t be prepared fo
da80: 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20  r any.** or all 
da90: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  of these interfa
daa0: 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f  ces to be NULL o
dab0: 72 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61  r for their beha
dac0: 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a  vior to change.*
dad0: 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61  * from one relea
dae0: 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20  se to the next. 
daf0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75   Applications mu
db00: 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74  st not attempt t
db10: 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20  o access.** any 
db20: 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73  of these methods
db30: 20 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e   if the iVersion
db40: 20 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c   of the VFS is l
db50: 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74  ess than 3..*/.t
db60: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
db70: 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65  lite3_vfs sqlite
db80: 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76  3_vfs;.typedef v
db90: 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79  oid (*sqlite3_sy
dba0: 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29  scall_ptr)(void)
dbb0: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
dbc0: 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  _vfs {.  int iVe
dbd0: 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20  rsion;          
dbe0: 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76    /* Structure v
dbf0: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63  ersion number (c
dc00: 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20  urrently 3) */. 
dc10: 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20   int szOsFile;  
dc20: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a            /* Siz
dc30: 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20  e of subclassed 
dc40: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a  sqlite3_file */.
dc50: 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65    int mxPathname
dc60: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61  ;          /* Ma
dc70: 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e  ximum file pathn
dc80: 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20  ame length */.  
dc90: 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65  sqlite3_vfs *pNe
dca0: 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74  xt;      /* Next
dcb0: 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20   registered VFS 
dcc0: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
dcd0: 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a  *zName;       /*
dce0: 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69   Name of this vi
dcf0: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
dd00: 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  m */.  void *pAp
dd10: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
dd20: 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70  /* Pointer to ap
dd30: 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66  plication-specif
dd40: 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74  ic data */.  int
dd50: 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
dd60: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
dd70: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
dd80: 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20  e3_file*,.      
dd90: 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61           int fla
dda0: 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61  gs, int *pOutFla
ddb0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  gs);.  int (*xDe
ddc0: 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lete)(sqlite3_vf
ddd0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
dde0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44  zName, int syncD
ddf0: 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63  ir);.  int (*xAc
de00: 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  cess)(sqlite3_vf
de10: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
de20: 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73  zName, int flags
de30: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
de40: 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61  .  int (*xFullPa
de50: 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  thname)(sqlite3_
de60: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
de70: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75   *zName, int nOu
de80: 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  t, char *zOut);.
de90: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65    void *(*xDlOpe
dea0: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
deb0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
dec0: 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20  lename);.  void 
ded0: 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69  (*xDlError)(sqli
dee0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
def0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d  yte, char *zErrM
df00: 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a  sg);.  void (*(*
df10: 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f  xDlSym)(sqlite3_
df20: 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73  vfs*,void*, cons
df30: 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29  t char *zSymbol)
df40: 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20  )(void);.  void 
df50: 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69  (*xDlClose)(sqli
df60: 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29  te3_vfs*, void*)
df70: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f  ;.  int (*xRando
df80: 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  mness)(sqlite3_v
df90: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
dfa0: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69  char *zOut);.  i
dfb0: 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c  nt (*xSleep)(sql
dfc0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d  ite3_vfs*, int m
dfd0: 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20  icroseconds);.  
dfe0: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
dff0: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
e000: 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e  , double*);.  in
e010: 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f  t (*xGetLastErro
e020: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
e030: 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20   int, char *);. 
e040: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
e050: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
e060: 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74  n version 1 of t
e070: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
e080: 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69  ject.  ** defini
e090: 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61  tion.  Those tha
e0a0: 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64  t follow are add
e0b0: 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20  ed in version 2 
e0c0: 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20  or later.  */.  
e0d0: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
e0e0: 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33  meInt64)(sqlite3
e0f0: 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69  _vfs*, sqlite3_i
e100: 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a  nt64*);.  /*.  *
e110: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
e120: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
e130: 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74  ons 1 and 2 of t
e140: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
e150: 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65  ject..  ** Those
e160: 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76   below are for v
e170: 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65  ersion 3 and gre
e180: 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74  ater..  */.  int
e190: 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c   (*xSetSystemCal
e1a0: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
e1b0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
e1c0: 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63  me, sqlite3_sysc
e1d0: 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69  all_ptr);.  sqli
e1e0: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20  te3_syscall_ptr 
e1f0: 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xGetSystemCall
e200: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e210: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
e220: 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  e);.  const char
e230: 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43   *(*xNextSystemC
e240: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
e250: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
e260: 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  Name);.  /*.  **
e270: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
e280: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
e290: 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f  ns 1 through 3 o
e2a0: 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73  f the sqlite_vfs
e2b0: 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65   object..  ** Ne
e2c0: 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  w fields may be 
e2d0: 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75  appended in figu
e2e0: 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68  re versions.  Th
e2f0: 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20  e iVersion.  ** 
e300: 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65  value will incre
e310: 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68  ment whenever th
e320: 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a  is happens. .  *
e330: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
e340: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20  3REF: Flags for 
e350: 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20  the xAccess VFS 
e360: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
e370: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
e380: 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64  ants can be used
e390: 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61   as the third pa
e3a0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
e3b0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
e3c0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
e3d0: 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  vfs] object.  Th
e3e0: 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20  ey determine.** 
e3f0: 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72  what kind of per
e400: 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63  missions the xAc
e410: 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c  cess method is l
e420: 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57  ooking for..** W
e430: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
e440: 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41  S_EXISTS, the xA
e450: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
e460: 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68  simply checks wh
e470: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65  ether the file e
e480: 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53  xists..** With S
e490: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
e4a0: 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63  DWRITE, the xAcc
e4b0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
e4c0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
e4d0: 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79   named directory
e4e0: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c   is both readabl
e4f0: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a  e and writable.*
e500: 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  * (in other word
e510: 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20  s, if files can 
e520: 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65  be added, remove
e530: 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77  d, and renamed w
e540: 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72  ithin.** the dir
e550: 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20  ectory)..** The 
e560: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
e570: 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74  ADWRITE constant
e580: 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73   is currently us
e590: 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a  ed only by the.*
e5a0: 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  * [temp_store_di
e5b0: 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c  rectory pragma],
e5c0: 20 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75   though this cou
e5d0: 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66  ld change in a f
e5e0: 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65  uture.** release
e5f0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57   of SQLite..** W
e600: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
e610: 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63  S_READ, the xAcc
e620: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
e630: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
e640: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
e650: 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41  e.  The SQLITE_A
e660: 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74  CCESS_READ const
e670: 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e  ant is.** curren
e680: 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75  tly unused, thou
e690: 67 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75  gh it might be u
e6a0: 73 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20  sed in a future 
e6b0: 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51  release of.** SQ
e6c0: 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
e6d0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
e6e0: 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69  XISTS    0.#defi
e6f0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
e700: 5f 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f  _READWRITE 1   /
e710: 2a 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41  * Used by PRAGMA
e720: 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65   temp_store_dire
e730: 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ctory */.#define
e740: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
e750: 45 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20  EAD      2   /* 
e760: 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  Unused */../*.**
e770: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
e780: 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63   for the xShmLoc
e790: 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  k VFS method.**.
e7a0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
e7b0: 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
e7c0: 65 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f  e the various lo
e7d0: 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73  cking operations
e7e0: 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74  .** allowed by t
e7f0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
e800: 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69  od of [sqlite3_i
e810: 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65  o_methods].  The
e820: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72  .** following ar
e830: 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c  e the only legal
e840: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66   combinations of
e850: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a   flags to the.**
e860: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
e870: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
e880: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
e890: 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  _LOCK | SQLITE_S
e8a0: 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69  HM_SHARED.** <li
e8b0: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  >  SQLITE_SHM_LO
e8c0: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
e8d0: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69  EXCLUSIVE.** <li
e8e0: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  >  SQLITE_SHM_UN
e8f0: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
e900: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
e910: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
e920: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
e930: 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f  _EXCLUSIVE.** </
e940: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75  ul>.**.** When u
e950: 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61  nlocking, the sa
e960: 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43  me SHARED or EXC
e970: 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74  LUSIVE flag must
e980: 20 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a   be supplied as.
e990: 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20  ** was given no 
e9a0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
e9b0: 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20  g lock.  .**.** 
e9c0: 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  The xShmLock met
e9d0: 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69  hod can transiti
e9e0: 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  on between unloc
e9f0: 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f  ked and SHARED o
ea00: 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c  r.** between unl
ea10: 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53  ocked and EXCLUS
ea20: 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20  IVE.  It cannot 
ea30: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
ea40: 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64  en SHARED.** and
ea50: 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23   EXCLUSIVE..*/.#
ea60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
ea70: 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31  M_UNLOCK       1
ea80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ea90: 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20  SHM_LOCK        
eaa0: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
eab0: 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20  E_SHM_SHARED    
eac0: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
ead0: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
eae0: 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41  E    8../*.** CA
eaf0: 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20  PI3REF: Maximum 
eb00: 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a  xShmLock index.*
eb10: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
eb20: 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c  k method on [sql
eb30: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
eb40: 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a   may use values.
eb50: 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ** between 0 and
eb60: 20 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e   this upper boun
eb70: 64 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74  d as its "offset
eb80: 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  " argument..** T
eb90: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77  he SQLite core w
eba0: 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70  ill never attemp
ebb0: 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20  t to acquire or 
ebc0: 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63  release a.** loc
ebd0: 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69  k outside of thi
ebe0: 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69  s range.*/.#defi
ebf0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c  ne SQLITE_SHM_NL
ec00: 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f  OCK        8.../
ec10: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
ec20: 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51  nitialize The SQ
ec30: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
ec40: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
ec50: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
ec60: 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73  tine initializes
ec70: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c   the.** SQLite l
ec80: 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71  ibrary.  ^The sq
ec90: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
eca0: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c   routine.** deal
ecb0: 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f  locates any reso
ecc0: 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20  urces that were 
ecd0: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
ece0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ecf0: 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  )..** These rout
ed00: 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65  ines are designe
ed10: 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63  d to aid in proc
ed20: 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ess initializati
ed30: 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f  on and.** shutdo
ed40: 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73  wn on embedded s
ed50: 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61  ystems.  Worksta
ed60: 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  tion application
ed70: 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74  s using.** SQLit
ed80: 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f  e normally do no
ed90: 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65  t need to invoke
eda0: 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65   either of these
edb0: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
edc0: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   A call to sqlit
edd0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
ede0: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
edf0: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a  " call if it is.
ee00: 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  ** the first tim
ee10: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
ee20: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
ee30: 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66  d during the lif
ee40: 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20  etime of.** the 
ee50: 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69  process, or if i
ee60: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74  t is the first t
ee70: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
ee80: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
ee90: 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  ked.** following
eea0: 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   a call to sqlit
eeb0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
eec0: 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74  ^(Only an effect
eed0: 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73  ive call.** of s
eee0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
eef0: 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69  e() does any ini
ef00: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c  tialization.  Al
ef10: 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a  l other calls.**
ef20: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
ef30: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20  -ops.)^.**.** A 
ef40: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
ef50: 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e  shutdown() is an
ef60: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
ef70: 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  l if it is the f
ef80: 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  irst.** call to 
ef90: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
efa0: 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73  () since the las
efb0: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
efc0: 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a  lize().  ^(Only.
efd0: 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ** an effective 
efe0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
eff0: 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20  shutdown() does 
f000: 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61  any deinitializa
f010: 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68  tion..** All oth
f020: 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74  er valid calls t
f030: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
f040: 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73  wn() are harmles
f050: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
f060: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
f070: 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72  itialize() inter
f080: 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61  face is threadsa
f090: 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f  fe, but sqlite3_
f0a0: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73  shutdown().** is
f0b0: 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74   not.  The sqlit
f0c0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e  e3_shutdown() in
f0d0: 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c  terface must onl
f0e0: 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  y be called from
f0f0: 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72   a.** single thr
f100: 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b  ead.  All open [
f110: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
f120: 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c  ions] must be cl
f130: 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20  osed and all.** 
f140: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73  other SQLite res
f150: 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64  ources must be d
f160: 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72  eallocated prior
f170: 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20   to invoking.** 
f180: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f190: 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20  ()..**.** Among 
f1a0: 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73  other things, ^s
f1b0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f1c0: 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a  e() will invoke.
f1d0: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
f1e0: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79  it().  Similarly
f1f0: 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64  , ^sqlite3_shutd
f200: 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e  own().** will in
f210: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f  voke sqlite3_os_
f220: 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  end()..**.** ^Th
f230: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
f240: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72  lize() routine r
f250: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
f260: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a  K] on success..*
f270: 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72  * ^If for some r
f280: 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69  eason, sqlite3_i
f290: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75  nitialize() is u
f2a0: 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c  nable to initial
f2b0: 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61  ize.** the libra
f2c0: 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69  ry (perhaps it i
f2d0: 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
f2e0: 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65  cate a needed re
f2f0: 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61  source such.** a
f300: 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65  s a mutex) it re
f310: 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20  turns an [error 
f320: 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e  code] other than
f330: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
f340: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
f350: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
f360: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
f370: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61  internally by ma
f380: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ny other.** SQLi
f390: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f  te interfaces so
f3a0: 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61   that an applica
f3b0: 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65  tion usually doe
f3c0: 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a  s not need to.**
f3d0: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
f3e0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
f3f0: 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d  ectly.  For exam
f400: 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ple, [sqlite3_op
f410: 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73  en()].** calls s
f420: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f430: 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74  e() so the SQLit
f440: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62  e library will b
f450: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
f460: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77  ** initialized w
f470: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  hen [sqlite3_ope
f480: 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69  n()] is called i
f490: 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20  f it has not be 
f4a0: 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61  initialized.** a
f4b0: 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65  lready.  ^Howeve
f4c0: 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  r, if SQLite is 
f4d0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
f4e0: 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
f4f0: 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70  UTOINIT].** comp
f500: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c  ile-time option,
f510: 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61   then the automa
f520: 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  tic calls to sql
f530: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f540: 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64  ).** are omitted
f550: 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
f560: 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73  tion must call s
f570: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f580: 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  e() directly.** 
f590: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
f5a0: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
f5b0: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20  interface.  For 
f5c0: 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c  maximum portabil
f5d0: 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65  ity,.** it is re
f5e0: 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
f5f0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61  pplications alwa
f600: 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ys invoke sqlite
f610: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
f620: 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72  * directly prior
f630: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
f640: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
f650: 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65  face.  Future re
f660: 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c  leases.** of SQL
f670: 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20  ite may require 
f680: 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20  this.  In other 
f690: 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76  words, the behav
f6a0: 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a  ior exhibited.**
f6b0: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
f6c0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
f6d0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
f6e0: 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d  NIT] might becom
f6f0: 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74  e the.** default
f700: 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d   behavior in som
f710: 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
f720: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
f730: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73  * The sqlite3_os
f740: 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20  _init() routine 
f750: 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73  does operating-s
f760: 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a  ystem specific.*
f770: 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  * initialization
f780: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c   of the SQLite l
f790: 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c  ibrary.  The sql
f7a0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
f7b0: 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20   routine undoes 
f7c0: 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71  the effect of sq
f7d0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
f7e0: 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a    Typical tasks.
f7f0: 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  ** performed by 
f800: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69  these routines i
f810: 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f  nclude allocatio
f820: 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f  n or deallocatio
f830: 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72  n.** of static r
f840: 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61  esources, initia
f850: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62  lization of glob
f860: 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a  al variables,.**
f870: 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65   setting up a de
f880: 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
f890: 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73  fs] module, or s
f8a0: 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64  etting up.** a d
f8b0: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
f8c0: 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69  tion using [sqli
f8d0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a  te3_config()]..*
f8e0: 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
f8f0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
f900: 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  r invoke either 
f910: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
f920: 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
f930: 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c  os_end() directl
f940: 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  y.  The applicat
f950: 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20  ion should only 
f960: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
f970: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
f980: 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nd sqlite3_shutd
f990: 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69  own().  The sqli
f9a0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
f9b0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61   interface is ca
f9c0: 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  lled automatical
f9d0: 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ly by sqlite3_in
f9e0: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a  itialize() and.*
f9f0: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  * sqlite3_os_end
fa00: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20  () is called by 
fa10: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
fa20: 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65  ().  Appropriate
fa30: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
fa40: 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  ons for sqlite3_
fa50: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
fa60: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
fa70: 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f  * are built into
fa80: 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20   SQLite when it 
fa90: 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  is compiled for 
faa0: 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f  Unix, Windows, o
fab0: 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20  r OS/2..** When 
fac0: 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c  [custom builds |
fad0: 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72   built for other
fae0: 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28   platforms].** (
faf0: 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
fb00: 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f  E_OS_OTHER=1] co
fb10: 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
fb20: 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63  tion) the applic
fb30: 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c  ation must suppl
fb40: 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70  y a suitable imp
fb50: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  lementation for.
fb60: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
fb70: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
fb80: 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61  _os_end().  An a
fb90: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c  pplication-suppl
fba0: 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ied.** implement
fbb0: 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
fbc0: 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71  _os_init() or sq
fbd0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
fbe0: 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53  * must return [S
fbf0: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
fc00: 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74  cess and some ot
fc10: 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  her [error code]
fc20: 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65   upon.** failure
fc30: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
fc40: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64  _initialize(void
fc50: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  );.int sqlite3_s
fc60: 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69  hutdown(void);.i
fc70: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  nt sqlite3_os_in
fc80: 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  it(void);.int sq
fc90: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69  lite3_os_end(voi
fca0: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
fcb0: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67  REF: Configuring
fcc0: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
fcd0: 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ary.**.** The sq
fce0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
fcf0: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
fd00: 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20   to make global 
fd10: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
fd20: 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69   changes to SQLi
fd30: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74  te in order to t
fd40: 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68  une SQLite to th
fd50: 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
fd60: 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
fd70: 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66  cation.  The def
fd80: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
fd90: 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  on is recommende
fda0: 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70  d for most.** ap
fdb0: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73  plications and s
fdc0: 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  o this routine i
fdd0: 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65  s usually not ne
fde0: 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a  cessary.  It is.
fdf0: 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  ** provided to s
fe00: 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c  upport rare appl
fe10: 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e  ications with un
fe20: 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a  usual needs..**.
fe30: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
fe40: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
fe50: 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  e is not threads
fe60: 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63  afe.  The applic
fe70: 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  ation.** must in
fe80: 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68  sure that no oth
fe90: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
fea0: 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64  aces are invoked
feb0: 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72   by other.** thr
fec0: 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74  eads while sqlit
fed0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72  e3_config() is r
fee0: 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72  unning.  Further
fef0: 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f  more, sqlite3_co
ff00: 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e  nfig().** may on
ff10: 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72  ly be invoked pr
ff20: 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69  ior to library i
ff30: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73  nitialization us
ff40: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
ff50: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72  initialize()] or
ff60: 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20   after shutdown 
ff70: 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  by [sqlite3_shut
ff80: 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20  down()]..** ^If 
ff90: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
ffa0: 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72   is called after
ffb0: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
ffc0: 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f  lize()] and befo
ffd0: 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  re.** [sqlite3_s
ffe0: 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20  hutdown()] then 
fff0: 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53  it will return S
10000 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a  QLITE_MISUSE..**
10010 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20   Note, however, 
10020 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f  that ^sqlite3_co
10030 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61  nfig() can be ca
10040 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  lled as part of 
10050 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
10060 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c  ation of an appl
10070 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
10080 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74  [sqlite3_os_init
10090 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ()]..**.** The f
100a0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
100b0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
100c0 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  ) is an integer.
100d0 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  ** [configuratio
100e0 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64  n option] that d
100f0 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61  etermines.** wha
10100 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51  t property of SQ
10110 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f  Lite is to be co
10120 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65  nfigured.  Subse
10130 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a  quent arguments.
10140 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ** vary dependin
10150 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67  g on the [config
10160 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a  uration option].
10170 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
10180 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
10190 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72  ^When a configur
101a0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
101b0 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  set, sqlite3_con
101c0 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53  fig() returns [S
101d0 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49  QLITE_OK]..** ^I
101e0 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20  f the option is 
101f0 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74  unknown or SQLit
10200 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73  e is unable to s
10210 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a  et the option.**
10220 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
10230 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  ne returns a non
10240 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
10250 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  e]..*/.int sqlit
10260 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e  e3_config(int, .
10270 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
10280 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20  3REF: Configure 
10290 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
102a0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ions.**.** The s
102b0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
102c0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
102d0 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e  used to make con
102e0 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
102f0 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61  anges to a [data
10300 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
10310 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  .  The interface
10320 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a   is similar to.*
10330 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
10340 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74  g()] except that
10350 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70   the changes app
10360 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a  ly to a single.*
10370 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
10380 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69  ection] (specifi
10390 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
103a0 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a  argument)..**.**
103b0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
103c0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
103d0 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e  db_config(D,V,..
103e0 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53  .)  is the.** [S
103f0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
10400 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69  OOKASIDE | confi
10410 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d  guration verb] -
10420 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
10430 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61   .** that indica
10440 74 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20  tes what aspect 
10450 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
10460 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
10470 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64  being configured
10480 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20  ..** Subsequent 
10490 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64  arguments vary d
104a0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
104b0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
104c0 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73  rb..**.** ^Calls
104d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
104e0 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53  onfig() return S
104f0 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20  QLITE_OK if and 
10500 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63  only if.** the c
10510 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65  all is considere
10520 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f  d successful..*/
10530 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f  .int sqlite3_db_
10540 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c  config(sqlite3*,
10550 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a   int op, ...);..
10560 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
10570 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
10580 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a  n Routines.**.**
10590 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
105a0 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  this object defi
105b0 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
105c0 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65  e between SQLite
105d0 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65  .** and low-leve
105e0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
105f0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ion routines..**
10600 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
10610 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20  is used in only 
10620 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65  one place in the
10630 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
10640 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  e..** A pointer 
10650 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
10660 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  f this object is
10670 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
10680 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
10690 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20  fig()] when the 
106a0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
106b0 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49  tion is.** [SQLI
106c0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
106d0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
106e0 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20  FIG_GETMALLOC]. 
106f0 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67   .** By creating
10700 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
10710 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61  this object.** a
10720 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  nd passing it to
10730 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
10740 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
10750 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72  _MALLOC]).** dur
10760 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
10770 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  n, an applicatio
10780 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e  n can specify an
10790 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
107a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
107b0 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20  n subsystem for 
107c0 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f  SQLite to use fo
107d0 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20  r all of its.** 
107e0 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e  dynamic memory n
107f0 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  eeds..**.** Note
10800 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d   that SQLite com
10810 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20  es with several 
10820 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79  [built-in memory
10830 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20   allocators].** 
10840 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74  that are perfect
10850 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20  ly adequate for 
10860 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67  the overwhelming
10870 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70   majority of app
10880 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64  lications.** and
10890 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63   that this objec
108a0 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c  t is only useful
108b0 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72   to a tiny minor
108c0 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
108d0 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63  ons.** with spec
108e0 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61  ialized memory a
108f0 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72  llocation requir
10900 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62  ements.  This ob
10910 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20  ject is.** also 
10920 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
10930 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e  ing of SQLite in
10940 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66   order to specif
10950 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
10960 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
10970 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61  ator that simula
10980 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f  tes memory out-o
10990 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69  f-memory conditi
109a0 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20  ons in.** order 
109b0 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53  to verify that S
109c0 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67  QLite recovers g
109d0 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73  racefully from s
109e0 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e  uch.** condition
109f0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61  s..**.** The xMa
10a00 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20  lloc, xRealloc, 
10a10 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64  and xFree method
10a20 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  s must work like
10a30 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
10a40 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  , realloc() and 
10a50 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73  free() functions
10a60 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
10a70 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
10a80 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
10a90 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63  ees that the sec
10aa0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
10ab0 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61  ** xRealloc is a
10ac0 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65  lways a value re
10ad0 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f  turned by a prio
10ae0 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64  r call to xRound
10af0 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20  up..**.** xSize 
10b00 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68  should return th
10b10 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
10b20 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   of a memory all
10b30 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69  ocation.** previ
10b40 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
10b50 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78  rom xMalloc or x
10b60 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c  Realloc.  The al
10b70 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20  located size.** 
10b80 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61  is always at lea
10b90 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65  st as big as the
10ba0 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20   requested size 
10bb0 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
10bc0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f  r..**.** The xRo
10bd0 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74  undup method ret
10be0 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20  urns what would 
10bf0 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  be the allocated
10c00 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65   size of.** a me
10c10 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10c20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c  given a particul
10c30 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  ar requested siz
10c40 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a  e.  Most memory.
10c50 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  ** allocators ro
10c60 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c  und up memory al
10c70 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61  locations at lea
10c80 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d  st to the next m
10c90 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e  ultiple.** of 8.
10ca0 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72    Some allocator
10cb0 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20  s round up to a 
10cc0 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  larger multiple 
10cd0 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66  or to a power of
10ce0 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d   2..** Every mem
10cf0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
10d00 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e  equest coming in
10d10 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65   through [sqlite
10d20 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f  3_malloc()].** o
10d30 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
10d40 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c  oc()] first call
10d50 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20  s xRoundup.  If 
10d60 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73  xRoundup returns
10d70 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75   0, .** that cau
10d80 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ses the correspo
10d90 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c  nding memory all
10da0 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e  ocation to fail.
10db0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74  .**.** The xInit
10dc0 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69   method initiali
10dd0 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  zes the memory a
10de0 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65  llocator.  For e
10df0 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69  xample,.** it mi
10e00 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79  ght allocate any
10e10 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73   require mutexes
10e20 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69   or initialize i
10e30 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20  nternal data.** 
10e40 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65  structures.  The
10e50 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f   xShutdown metho
10e60 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e  d is invoked (in
10e70 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20  directly) by.** 
10e80 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
10e90 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20  n()] and should 
10ea0 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  deallocate any r
10eb0 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65  esources acquire
10ec0 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20  d.** by xInit.  
10ed0 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69  The pAppData poi
10ee0 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20  nter is used as 
10ef0 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
10f00 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61  er to.** xInit a
10f10 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a  nd xShutdown..**
10f20 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73  .** SQLite holds
10f30 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
10f40 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52  EX_STATIC_MASTER
10f50 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20  ] mutex when it 
10f60 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78  invokes.** the x
10f70 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20  Init method, so 
10f80 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
10f90 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72   need not be thr
10fa0 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a  eadsafe.  The.**
10fb0 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f   xShutdown metho
10fc0 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64  d is only called
10fd0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73   from [sqlite3_s
10fe0 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74  hutdown()] so it
10ff0 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65   does.** not nee
11000 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61  d to be threadsa
11010 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20  fe either.  For 
11020 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64  all other method
11030 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c  s, SQLite.** hol
11040 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d  ds the [SQLITE_M
11050 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d  UTEX_STATIC_MEM]
11060 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61   mutex as long a
11070 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
11080 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
11090 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  S] configuration
110a0 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65   option is turne
110b0 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69  d on (which.** i
110c0 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29  t is by default)
110d0 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68   and so the meth
110e0 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69  ods are automati
110f0 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64  cally serialized
11100 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66  ..** However, if
11110 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
11120 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69  MEMSTATUS] is di
11130 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65  sabled, then the
11140 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64   other.** method
11150 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64  s must be thread
11160 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b  safe or else mak
11170 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61  e their own arra
11180 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20  ngements for.** 
11190 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a  serialization..*
111a0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c  *.** SQLite will
111b0 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49   never invoke xI
111c0 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20  nit() more than 
111d0 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20  once without an 
111e0 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63  intervening.** c
111f0 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e  all to xShutdown
11200 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ()..*/.typedef s
11210 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65  truct sqlite3_me
11220 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  m_methods sqlite
11230 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73  3_mem_methods;.s
11240 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65  truct sqlite3_me
11250 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f  m_methods {.  vo
11260 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69  id *(*xMalloc)(i
11270 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20  nt);         /* 
11280 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
11290 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20  n function */.  
112a0 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f  void (*xFree)(vo
112b0 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f  id*);          /
112c0 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61  * Free a prior a
112d0 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76  llocation */.  v
112e0 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29  oid *(*xRealloc)
112f0 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a  (void*,int);  /*
11300 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63   Resize an alloc
11310 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
11320 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20  *xSize)(void*); 
11330 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74            /* Ret
11340 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  urn the size of 
11350 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
11360 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75  .  int (*xRoundu
11370 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  p)(int);        
11380 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65    /* Round up re
11390 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c  quest size to al
113a0 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f  location size */
113b0 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28  .  int (*xInit)(
113c0 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
113d0 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20    /* Initialize 
113e0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
113f0 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28  ator */.  void (
11400 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64  *xShutdown)(void
11410 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e  *);      /* Dein
11420 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
11430 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
11440 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
11450 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  a;              
11460 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f    /* Argument to
11470 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68   xInit() and xSh
11480 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a  utdown() */.};..
11490 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
114a0 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
114b0 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  tions.** KEYWORD
114c0 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f  S: {configuratio
114d0 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20  n option}.**.** 
114e0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
114f0 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
11500 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
11510 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
11520 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
11530 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
11540 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
11550 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
11560 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
11570 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
11580 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
11590 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
115a0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
115b0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
115c0 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
115d0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
115e0 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
115f0 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
11600 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
11610 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
11620 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
11630 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
11640 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
11650 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
11660 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63    The [sqlite3_c
11670 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
11680 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
11690 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
116a0 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
116b0 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
116c0 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
116d0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
116e0 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
116f0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
11700 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
11710 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e  GLETHREAD]] <dt>
11720 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
11730 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a  NGLETHREAD</dt>.
11740 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
11750 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
11760 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
11770 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
11780 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
11790 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67  ng mode] to Sing
117a0 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  le-thread.  In o
117b0 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
117c0 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  isables.** all m
117d0 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73  utexing and puts
117e0 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d   SQLite into a m
117f0 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e  ode where it can
11800 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a   only be used.**
11810 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72   by a single thr
11820 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ead.   ^If SQLit
11830 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
11840 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
11850 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
11860 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
11870 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
11880 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
11890 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
118a0 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  le to change the
118b0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
118c0 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75  ] from its defau
118d0 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53  lt.** value of S
118e0 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64  ingle-thread and
118f0 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   so [sqlite3_con
11900 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
11910 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  rn .** [SQLITE_E
11920 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
11930 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
11940 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
11950 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  EAD.** configura
11960 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
11970 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
11980 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
11990 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAD]] <dt>SQLITE
119a0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
119b0 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
119c0 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
119d0 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
119e0 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
119f0 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
11a00 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
11a10 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61  ] to Multi-threa
11a20 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
11a30 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
11a40 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b  ** mutexing on [
11a50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11a60 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
11a70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
11a80 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70  jects..** The ap
11a90 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73  plication is res
11aa0 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72  ponsible for ser
11ab0 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20  ializing access 
11ac0 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  to.** [database 
11ad0 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64  connections] and
11ae0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
11af0 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68  ments].  But oth
11b00 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  er mutexes.** ar
11b10 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61  e enabled so tha
11b20 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  t SQLite will be
11b30 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20   safe to use in 
11b40 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
11b50 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20  .** environment 
11b60 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77  as long as no tw
11b70 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70  o threads attemp
11b80 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d  t to use the sam
11b90 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
11ba0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68  onnection] at th
11bb0 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49  e same time.  ^I
11bc0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
11bd0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
11be0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
11bf0 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
11c00 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
11c10 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
11c20 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
11c30 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74   possible to set
11c40 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61   the Multi-threa
11c50 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
11c60 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
11c70 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
11c80 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
11c90 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
11ca0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
11cb0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
11cc0 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72  ITHREAD configur
11cd0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
11ce0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
11cf0 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
11d00 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  ZED]] <dt>SQLITE
11d10 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
11d20 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
11d30 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
11d40 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
11d50 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
11d60 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
11d70 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
11d80 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20   to Serialized. 
11d90 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
11da0 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62  this option enab
11db0 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78  les.** all mutex
11dc0 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65  es including the
11dd0 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75   recursive.** mu
11de0 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61  texes on [databa
11df0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
11e00 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
11e10 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e  tement] objects.
11e20 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65  .** In this mode
11e30 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64   (which is the d
11e40 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69  efault when SQLi
11e50 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
11e60 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54  ith.** [SQLITE_T
11e70 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68  HREADSAFE=1]) th
11e80 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
11e90 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72   will itself ser
11ea0 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a  ialize access.**
11eb0 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f   to [database co
11ec0 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
11ed0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
11ee0 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65  nts] so that the
11ef0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  .** application 
11f00 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74  is free to use t
11f10 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
11f20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72  e connection] or
11f30 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72   the.** same [pr
11f40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
11f50 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74  ] in different t
11f60 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
11f70 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20  me time..** ^If 
11f80 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
11f90 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
11fa0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
11fb0 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
11fc0 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
11fd0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
11fe0 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
11ff0 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
12000 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74  he Serialized [t
12010 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
12020 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
12030 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
12040 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
12050 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
12060 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
12070 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
12080 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ED configuration
12090 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
120a0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
120b0 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  FIG_MALLOC]] <dt
120c0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
120d0 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
120e0 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
120f0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
12100 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
12110 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
12120 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
12130 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
12140 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
12150 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d  ture.  The argum
12160 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
12170 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
12180 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
12190 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
121a0 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20  s to be used in 
121b0 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  place of.** the 
121c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
121d0 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  n routines built
121e0 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
121f0 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a  ^SQLite makes.**
12200 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
12210 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e   copy of the con
12220 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
12230 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
12240 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62  ] structure.** b
12250 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74  efore the [sqlit
12260 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c  e3_config()] cal
12270 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a  l returns.</dd>.
12280 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
12290 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d  ONFIG_GETMALLOC]
122a0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
122b0 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64  FIG_GETMALLOC</d
122c0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
122d0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
122e0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
122f0 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
12300 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
12310 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
12320 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
12330 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
12340 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
12350 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
12360 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
12370 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
12380 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72  ly defined memor
12390 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
123a0 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73  tines.)^.** This
123b0 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
123c0 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
123d0 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  the default memo
123e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
123f0 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
12400 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69   wrapper that si
12410 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79  mulations memory
12420 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
12430 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73  ure or.** tracks
12440 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66   memory usage, f
12450 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64  or example. </dd
12460 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12470 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
12480 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  S]] <dt>SQLITE_C
12490 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c  ONFIG_MEMSTATUS<
124a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
124b0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
124c0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
124d0 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74  of type int, int
124e0 65 72 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a  erpreted as a .*
124f0 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68  * boolean, which
12500 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
12510 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74  bles the collect
12520 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c  ion of memory al
12530 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61  location .** sta
12540 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20  tistics. ^(When 
12550 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12560 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
12570 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a   disabled, the .
12580 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  ** following SQL
12590 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62  ite interfaces b
125a0 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74  ecome non-operat
125b0 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e  ional:.**   <ul>
125c0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
125d0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
125e0 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
125f0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
12600 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c  hwater()].**   <
12610 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66  li> [sqlite3_sof
12620 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
12630 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
12640 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a  ite3_status()].*
12650 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e  *   </ul>)^.** ^
12660 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
12670 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
12680 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61   enabled by defa
12690 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74  ult unless SQLit
126a0 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  e is.** compiled
126b0 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45   with [SQLITE_DE
126c0 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d  FAULT_MEMSTATUS]
126d0 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  =0 in which case
126e0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
126f0 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
12700 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79   are disabled by
12710 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64   default..** </d
12720 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12730 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
12740 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
12750 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74  NFIG_SCRATCH</dt
12760 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
12770 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
12780 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
12790 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c   buffer that SQL
127a0 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a  ite can use for.
127b0 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
127c0 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68  y.  There are th
127d0 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20  ree arguments:  
127e0 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62  A pointer an 8-b
127f0 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d  yte.** aligned m
12800 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f  emory buffer fro
12810 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61  m which the scra
12820 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  tch allocations 
12830 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e  will be.** drawn
12840 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
12850 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  ch scratch alloc
12860 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61  ation (sz),.** a
12870 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  nd the maximum n
12880 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68  umber of scratch
12890 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29   allocations (N)
128a0 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67  .  The sz.** arg
128b0 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
128c0 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a  multiple of 16..
128d0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
128e0 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
128f0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d  pointer to an 8-
12900 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66  byte aligned buf
12910 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  fer.** of at lea
12920 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
12930 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c   memory..** ^SQL
12940 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20  ite will use no 
12950 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63  more than two sc
12960 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65  ratch buffers pe
12970 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a  r thread.  So.**
12980 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74   N should be set
12990 20 74 6f 20 74 77 69 63 65 20 74 68 65 20 65 78   to twice the ex
129a0 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e  pected maximum n
129b0 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73  umber of threads
129c0 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
129d0 6c 20 6e 65 76 65 72 20 72 65 71 75 69 72 65 20  l never require 
129e0 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  a scratch buffer
129f0 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68   that is more th
12a00 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68  an 6.** times th
12a10 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
12a20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65  size. ^If SQLite
12a30 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64   needs needs add
12a40 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74  itional.** scrat
12a50 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64  ch memory beyond
12a60 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
12a70 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67  d by this config
12a80 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20  uration option, 
12a90 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  then .** [sqlite
12aa0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c  3_malloc()] will
12ab0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
12ac0 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65  in the memory ne
12ad0 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  eded.</dd>.**.**
12ae0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
12af0 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74  _PAGECACHE]] <dt
12b00 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
12b10 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a  AGECACHE</dt>.**
12b20 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
12b30 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
12b40 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
12b50 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
12b60 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74  can use for.** t
12b70 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
12b80 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20   cache with the 
12b90 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63  default page cac
12ba0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
12bb0 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e  n.  .** This con
12bc0 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c  figuration shoul
12bd0 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66  d not be used if
12be0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
12bf0 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63  define page.** c
12c00 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
12c10 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73  ion is loaded us
12c20 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ing the SQLITE_C
12c30 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70  ONFIG_PCACHE2 op
12c40 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61  tion..** There a
12c50 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
12c60 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
12c70 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  n: A pointer to 
12c80 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a  8-byte aligned.*
12c90 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69  * memory, the si
12ca0 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20  ze of each page 
12cb0 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64  buffer (sz), and
12cc0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70   the number of p
12cd0 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65  ages (N)..** The
12ce0 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f   sz argument sho
12cf0 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20  uld be the size 
12d00 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64  of the largest d
12d10 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20  atabase page.** 
12d20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20  (a power of two 
12d30 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20  between 512 and 
12d40 33 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69  32768) plus a li
12d50 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65  ttle extra for e
12d60 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64  ach.** page head
12d70 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68  er.  ^The page h
12d80 65 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 30  eader size is 20
12d90 20 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 70   to 40 bytes dep
12da0 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65  ending on.** the
12db0 20 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 75   host architectu
12dc0 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d  re.  ^It is harm
12dd0 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d  less, apart from
12de0 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f   the wasted memo
12df0 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73  ry,.** to make s
12e00 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c  z a little too l
12e10 61 72 67 65 2e 20 20 54 68 65 20 66 69 72 73 74  arge.  The first
12e20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  .** argument sho
12e30 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20  uld point to an 
12e40 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74  allocation of at
12e50 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
12e60 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  s of memory..** 
12e70 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
12e80 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76   the memory prov
12e90 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ided by the firs
12ea0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61  t argument to sa
12eb0 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d  tisfy its.** mem
12ec0 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68  ory needs for th
12ed0 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20  e first N pages 
12ee0 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20  that it adds to 
12ef0 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69  cache.  ^If addi
12f00 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63  tional.** page c
12f10 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e  ache memory is n
12f20 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61  eeded beyond wha
12f30 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  t is provided by
12f40 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68   this option, th
12f50 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65  en.** SQLite goe
12f60 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  s to [sqlite3_ma
12f70 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20  lloc()] for the 
12f80 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61  additional stora
12f90 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65  ge space..** The
12fa0 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20   pointer in the 
12fb0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
12fc0 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65  ust.** be aligne
12fd0 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62  d to an 8-byte b
12fe0 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65  oundary or subse
12ff0 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f  quent behavior o
13000 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c  f SQLite.** will
13010 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f   be undefined.</
13020 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13030 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d  TE_CONFIG_HEAP]]
13040 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13050 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20  IG_HEAP</dt>.** 
13060 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
13070 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
13080 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
13090 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  er that SQLite w
130a0 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61  ill use.** for a
130b0 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
130c0 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  c memory allocat
130d0 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64  ion needs beyond
130e0 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a   those provided.
130f0 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54  ** for by [SQLIT
13100 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
13110 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f  ] and [SQLITE_CO
13120 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e  NFIG_PAGECACHE].
13130 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68  .** There are th
13140 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41  ree arguments: A
13150 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  n 8-byte aligned
13160 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
13170 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e  memory,.** the n
13180 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
13190 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66  n the memory buf
131a0 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e  fer, and the min
131b0 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
131c0 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  size..** ^If the
131d0 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28   first pointer (
131e0 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  the memory point
131f0 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  er) is NULL, the
13200 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73  n SQLite reverts
13210 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73  .** to using its
13220 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20   default memory 
13230 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73  allocator (the s
13240 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69  ystem malloc() i
13250 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a  mplementation),.
13260 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70  ** undoing any p
13270 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20  rior invocation 
13280 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  of [SQLITE_CONFI
13290 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20  G_MALLOC].  ^If 
132a0 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f  the.** memory po
132b0 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
132c0 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51  L and either [SQ
132d0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
132e0 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  YS3] or.** [SQLI
132f0 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
13300 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20  5] are defined, 
13310 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61  then the alterna
13320 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  tive memory.** a
13330 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61  llocator is enga
13340 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c  ged to handle al
13350 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d  l of SQLites mem
13360 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
13370 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  eeds..** The fir
13380 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20  st pointer (the 
13390 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20  memory pointer) 
133a0 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20  must be aligned 
133b0 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  to an 8-byte.** 
133c0 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73  boundary or subs
133d0 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20  equent behavior 
133e0 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  of SQLite will b
133f0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  e undefined..** 
13400 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  The minimum allo
13410 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63  cation size is c
13420 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20  apped at 2**12. 
13430 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65  Reasonable value
13440 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e  s.** for the min
13450 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
13460 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68  size are 2**5 th
13470 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e  rough 2**8.</dd>
13480 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13490 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c  CONFIG_MUTEX]] <
134a0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
134b0 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  _MUTEX</dt>.** <
134c0 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
134d0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
134e0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
134f0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
13500 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
13510 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
13520 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
13530 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
13540 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
13550 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
13560 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20  low-level mutex 
13570 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
13580 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20  sed in place.** 
13590 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  the mutex routin
135a0 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
135b0 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65  Lite.)^  ^SQLite
135c0 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
135d0 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20   the.** content 
135e0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
135f0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
13600 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20  tructure before 
13610 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  the call to.** [
13620 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
13630 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53  ] returns. ^If S
13640 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
13650 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
13660 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
13670 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
13680 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
13690 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
136a0 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
136b0 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
136c0 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
136d0 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
136e0 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
136f0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
13700 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
13710 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
13720 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  X configuration 
13730 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72  option will.** r
13740 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
13750 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ROR].</dd>.**.**
13760 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13770 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e  _GETMUTEX]] <dt>
13780 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
13790 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  TMUTEX</dt>.** <
137a0 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
137b0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
137c0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
137d0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
137e0 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
137f0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
13800 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
13810 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a  ructure.  The.**
13820 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
13830 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
13840 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
13850 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
13860 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78  ly defined mutex
13870 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
13880 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
13890 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
138a0 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
138b0 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e  mutex allocation
138c0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
138d0 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64  h a wrapper used
138e0 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20   to track mutex 
138f0 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72  usage for perfor
13900 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69  mance.** profili
13910 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66  ng or testing, f
13920 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49  or example.   ^I
13930 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
13940 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
13950 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
13960 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
13970 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
13980 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
13990 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72  hen.** the entir
139a0 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79  e mutexing subsy
139b0 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20  stem is omitted 
139c0 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61  from the build a
139d0 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74  nd hence calls t
139e0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
139f0 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65  nfig()] with the
13a00 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
13a10 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  ETMUTEX configur
13a20 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
13a30 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
13a40 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
13a50 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13a60 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
13a70 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13a80 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
13a90 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
13aa0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
13ab0 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68  two arguments th
13ac0 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  at determine the
13ad0 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f   default.** memo
13ae0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f  ry allocation fo
13af0 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  r the lookaside 
13b00 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
13b10 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74   on each.** [dat
13b20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13b30 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72  ].  The first ar
13b40 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
13b50 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
13b60 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
13b70 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f  lot and the seco
13b80 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nd is the number
13b90 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c   of.** slots all
13ba0 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64  ocated to each d
13bb0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13bc0 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70  on.)^  ^(This op
13bd0 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
13be0 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20   <i>default</i> 
13bf0 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20  lookaside size. 
13c00 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f  The [SQLITE_DBCO
13c10 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a  NFIG_LOOKASIDE].
13c20 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69  ** verb to [sqli
13c30 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
13c40 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
13c50 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61  change the looka
13c60 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  side.** configur
13c70 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
13c80 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e  ual connections.
13c90 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  )^ </dd>.**.** [
13ca0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
13cb0 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c  CACHE2]] <dt>SQL
13cc0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
13cd0 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  E2</dt>.** <dd> 
13ce0 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
13cf0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
13d00 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
13d10 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61   pointer to.** a
13d20 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
13d30 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
13d40 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ct.  This object
13d50 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 69   specifies the i
13d60 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61  nterface.** to a
13d70 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63   custom page cac
13d80 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
13d90 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61  n.)^  ^SQLite ma
13da0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
13db0 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20  e.** object and 
13dc0 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67 65  uses it for page
13dd0 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c   cache memory al
13de0 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a  locations.</dd>.
13df0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13e00 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
13e10 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13e20 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c  NFIG_GETPCACHE2<
13e30 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
13e40 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
13e50 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
13e60 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
13e70 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
13e80 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
13e90 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
13ea0 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20    SQLite copies 
13eb0 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
13ec0 2a 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  * page cache imp
13ed0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f  lementation into
13ee0 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20   that object.)^ 
13ef0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13f00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d  LITE_CONFIG_LOG]
13f10 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13f20 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20  FIG_LOG</dt>.** 
13f30 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f  <dd> The SQLITE_
13f40 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f  CONFIG_LOG optio
13f50 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  n is used to con
13f60 66 69 67 75 72 65 20 74 68 65 20 53 51 4c 69 74  figure the SQLit
13f70 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72  e.** global [err
13f80 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68  or log]..** (^Th
13f90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13fa0 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOG option takes
13fb0 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20   two arguments: 
13fc0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a  a pointer to a.*
13fd0 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  * function with 
13fe0 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65  a call signature
13ff0 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   of void(*)(void
14000 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
14010 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f  *), .** and a po
14020 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e  inter to void. ^
14030 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
14040 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
14050 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e  ULL, it is.** in
14060 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65  voked by [sqlite
14070 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63  3_log()] to proc
14080 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67  ess each logging
14090 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
140a0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  .** function poi
140b0 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68  nter is NULL, th
140c0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  e [sqlite3_log()
140d0 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f  ] interface beco
140e0 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20  mes a no-op..** 
140f0 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65  ^The void pointe
14100 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65  r that is the se
14110 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
14120 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
14130 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20  OG is.** passed 
14140 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
14150 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
14160 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
14170 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
14180 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  .** function whe
14190 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74  never that funct
141a0 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ion is invoked. 
141b0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
141c0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
141d0 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
141e0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
141f0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
14200 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70  r to the corresp
14210 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  onding.** [sqlit
14220 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61  e3_log()] call a
14230 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  nd is intended t
14240 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63  o be a [result c
14250 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  ode] or an.** [e
14260 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
14270 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72  ode].  ^The thir
14280 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73  d parameter pass
14290 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72  ed to the logger
142a0 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61   is.** log messa
142b0 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74  ge after formatt
142c0 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ing via [sqlite3
142d0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a  _snprintf()]..**
142e0 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67   The SQLite logg
142f0 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73  ing interface is
14300 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20   not reentrant; 
14310 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
14320 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20  ion.** supplied 
14330 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
14340 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f  on must not invo
14350 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  ke any SQLite in
14360 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61  terface..** In a
14370 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20   multi-threaded 
14380 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65  application, the
14390 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
143a0 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
143b0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  unction must be 
143c0 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64  threadsafe. </dd
143d0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
143e0 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64  _CONFIG_URI]] <d
143f0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14400 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 69  URI.** <dd>^(Thi
14410 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
14420 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
14430 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66   of type int. If
14440 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a   non-zero, then.
14450 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  ** URI handling 
14460 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62  is globally enab
14470 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61  led. If the para
14480 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74  meter is zero, t
14490 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  hen URI handling
144a0 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  .** is globally 
144b0 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20  disabled.)^ ^If 
144c0 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
144d0 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64  globally enabled
144e0 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a  , all filenames.
144f0 2a 2a 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71  ** passed to [sq
14500 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
14510 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
14520 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
14530 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65  n16()] or.** spe
14540 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f  cified as part o
14550 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61  f [ATTACH] comma
14560 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65  nds are interpre
14570 74 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67  ted as URIs, reg
14580 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68  ardless.** of wh
14590 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
145a0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
145b0 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77  I] flag is set w
145c0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
145d0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
145e0 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74  s opened. ^If it
145f0 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73   is globally dis
14600 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73  abled, filenames
14610 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74   are.** only int
14620 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
14630 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f   if the SQLITE_O
14640 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20  PEN_URI flag is 
14650 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20  set when the.** 
14660 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14670 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e  ion is opened. ^
14680 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49  (By default, URI
14690 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
146a0 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65  bally.** disable
146b0 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  d. The default v
146c0 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e  alue may be chan
146d0 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67  ged by compiling
146e0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
146f0 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79  LITE_USE_URI] sy
14700 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a  mbol defined.)^.
14710 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14720 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
14730 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e  NDEX_SCAN]] <dt>
14740 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
14750 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
14760 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 69 73 20 6f  N.** <dd>^This o
14770 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
14780 6e 67 6c 65 20 69 6e 74 65 67 65 72 20 61 72 67  ngle integer arg
14790 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 69  ument which is i
147a0 6e 74 65 72 70 72 65 74 65 64 20 61 73 0a 2a 2a  nterpreted as.**
147b0 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72   a boolean in or
147c0 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  der to enable or
147d0 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65   disable the use
147e0 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64   of covering ind
147f0 69 63 65 73 20 66 6f 72 0a 2a 2a 20 66 75 6c 6c  ices for.** full
14800 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20   table scans in 
14810 74 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69  the query optimi
14820 7a 65 72 2e 20 20 5e 54 68 65 20 64 65 66 61 75  zer.  ^The defau
14830 6c 74 20 73 65 74 74 69 6e 67 20 69 73 20 64 65  lt setting is de
14840 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74  termined.** by t
14850 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57  he [SQLITE_ALLOW
14860 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
14870 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SCAN] compile-ti
14880 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73  me option, or is
14890 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74   "on".** if that
148a0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
148b0 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e  tion is omitted.
148c0 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20  .** The ability 
148d0 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20 75  to disable the u
148e0 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69  se of covering i
148f0 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20  ndices for full 
14900 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69  table scans.** i
14910 73 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69  s because some i
14920 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64  ncorrectly coded
14930 20 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61 74   legacy applicat
14940 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75  ions might malfu
14950 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74  nction.** when t
14960 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20  he optimization 
14970 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f  is enabled.  Pro
14980 76 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69  viding the abili
14990 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65  ty to.** disable
149a0 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f   the optimizatio
149b0 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64  n allows the old
149c0 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63  er, buggy applic
149d0 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f  ation code to wo
149e0 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68  rk.** without ch
149f0 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e  ange even with n
14a00 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  ewer versions of
14a10 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b   SQLite..**.** [
14a20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
14a30 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45  CACHE]] [[SQLITE
14a40 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
14a50 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  E]].** <dt>SQLIT
14a60 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
14a70 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  and SQLITE_CONFI
14a80 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c  G_GETPCACHE.** <
14a90 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e  dd> These option
14aa0 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61  s are obsolete a
14ab0 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  nd should not be
14ac0 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64   used by new cod
14ad0 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72  e..** They are r
14ae0 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b  etained for back
14af0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
14b00 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20  ity but are now 
14b10 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e  no-ops..** </dd>
14b20 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14b30 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a  CONFIG_SQLLOG]].
14b40 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
14b50 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c  NFIG_SQLLOG.** <
14b60 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  dd>This option i
14b70 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
14b80 20 69 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f   if sqlite is co
14b90 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
14ba0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
14bb0 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72  E_SQLLOG] pre-pr
14bc0 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65  ocessor macro de
14bd0 66 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74  fined. The first
14be0 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
14bf0 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72  .** be a pointer
14c00 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f   to a function o
14c10 66 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76  f type void(*)(v
14c20 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f  oid*,sqlite3*,co
14c30 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e  nst char*, int).
14c40 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73  .** The second s
14c50 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65  hould be of type
14c60 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61   (void*). The ca
14c70 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
14c80 64 20 62 79 20 74 68 65 20 6c 69 62 72 61 72 79  d by the library
14c90 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70  .** in three sep
14ca0 61 72 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e  arate circumstan
14cb0 63 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20  ces, identified 
14cc0 62 79 20 74 68 65 20 76 61 6c 75 65 20 70 61 73  by the value pas
14cd0 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f  sed as the.** fo
14ce0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20  urth parameter. 
14cf0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
14d00 72 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68  rameter is 0, th
14d10 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
14d20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61  connection.** pa
14d30 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
14d40 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20  nd argument has 
14d50 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64  just been opened
14d60 2e 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75  . The third argu
14d70 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74  ment.** points t
14d80 6f 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61  o a buffer conta
14d90 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f  ining the name o
14da0 66 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62  f the main datab
14db0 61 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65  ase file. If the
14dc0 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d  .** fourth param
14dd0 65 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20  eter is 1, then 
14de0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
14df0 74 20 74 68 61 74 20 74 68 65 20 74 68 69 72 64  t that the third
14e00 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f   parameter.** po
14e10 69 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74  ints to has just
14e20 20 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20   been executed. 
14e30 4f 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74  Or, if the fourt
14e40 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 32  h parameter is 2
14e50 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f  , then.** the co
14e60 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70  nnection being p
14e70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
14e80 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
14e90 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54   being closed. T
14ea0 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61  he.** third para
14eb0 6d 65 74 65 72 20 69 73 20 70 61 73 73 65 64 20  meter is passed 
14ec0 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73  NULL In this cas
14ed0 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f  e.  An example o
14ee0 66 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20  f using this.** 
14ef0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
14f00 74 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e  tion can be seen
14f10 20 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71   in the "test_sq
14f20 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66  llog.c" source f
14f30 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61  ile in.** the ca
14f40 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73  nonical SQLite s
14f50 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e  ource tree.</dd>
14f60 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14f70 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
14f80 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
14f90 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
14fa0 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45  E.** <dd>^SQLITE
14fb0 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
14fc0 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62  E takes two 64-b
14fd0 69 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69  it integer (sqli
14fe0 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65  te3_int64) value
14ff0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68  s.** that are th
15000 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73  e default mmap s
15010 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64  ize limit (the d
15020 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66  efault setting f
15030 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d  or.** [PRAGMA mm
15040 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68  ap_size]) and th
15050 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65  e maximum allowe
15060 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69  d mmap size limi
15070 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  t..** ^The defau
15080 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62  lt setting can b
15090 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20  e overridden by 
150a0 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
150b0 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  nnection using.*
150c0 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b 50 52  * either the [PR
150d0 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20  AGMA mmap_size] 
150e0 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75  command, or by u
150f0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  sing the.** [SQL
15100 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
15110 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  IZE] file contro
15120 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75  l.  ^(The maximu
15130 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73  m allowed mmap s
15140 69 7a 65 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65  ize.** cannot be
15150 20 63 68 61 6e 67 65 64 20 61 74 20 72 75 6e 2d   changed at run-
15160 74 69 6d 65 2e 20 20 4e 6f 72 20 6d 61 79 20 74  time.  Nor may t
15170 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77  he maximum allow
15180 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20  ed mmap size.** 
15190 65 78 63 65 65 64 20 74 68 65 20 63 6f 6d 70 69  exceed the compi
151a0 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20  le-time maximum 
151b0 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79  mmap size set by
151c0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
151d0 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63  MAX_MMAP_SIZE] c
151e0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
151f0 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74  on.)^.** ^If eit
15200 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  her argument to 
15210 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e  this option is n
15220 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
15230 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  at argument is.*
15240 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73  * changed to its
15250 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65   compile-time de
15260 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  fault..**.** [[S
15270 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
15280 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a  32_HEAPSIZE]].**
15290 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
152a0 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
152b0 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 69 73 20 6f  E.** <dd>^This o
152c0 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76  ption is only av
152d0 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74  ailable if SQLit
152e0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f  e is compiled fo
152f0 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 77 69 74  r Windows.** wit
15300 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49  h the [SQLITE_WI
15310 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d  N32_MALLOC] pre-
15320 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
15330 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 53 51 4c 49  defined..** SQLI
15340 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
15350 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61  HEAPSIZE takes a
15360 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64   32-bit unsigned
15370 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a   integer value.*
15380 2a 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  * that specifies
15390 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a   the maximum siz
153a0 65 20 6f 66 20 74 68 65 20 63 72 65 61 74 65 64  e of the created
153b0 20 68 65 61 70 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a   heap..** </dl>.
153c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
153d0 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
153e0 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c  HREAD  1  /* nil
153f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15400 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
15410 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69  HREAD   2  /* ni
15420 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
15430 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
15440 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e  LIZED    3  /* n
15450 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
15460 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
15470 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20  OC        4  /* 
15480 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
15490 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
154a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
154b0 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f  TMALLOC     5  /
154c0 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
154d0 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
154e0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
154f0 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20  SCRATCH       6 
15500 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
15510 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
15520 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15530 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20  G_PAGECACHE     
15540 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  7  /* void*, int
15550 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
15560 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15570 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20  FIG_HEAP        
15580 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    8  /* void*, i
15590 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69  nt nByte, int mi
155a0 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
155b0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
155c0 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62  ATUS     9  /* b
155d0 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e  oolean */.#defin
155e0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
155f0 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20  MUTEX        10 
15600 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
15610 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  x_methods* */.#d
15620 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15630 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20  FIG_GETMUTEX    
15640 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   11  /* sqlite3_
15650 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
15660 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  /./* previously 
15670 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48  SQLITE_CONFIG_CH
15680 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63  UNKALLOC 12 whic
15690 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e  h is now unused.
156a0 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c   */ .#define SQL
156b0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
156c0 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69  SIDE    13  /* i
156d0 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  nt int */.#defin
156e0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
156f0 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20  PCACHE       14 
15700 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65   /* no-op */.#de
15710 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15720 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20  IG_GETPCACHE    
15730 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a  15  /* no-op */.
15740 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15750 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20  ONFIG_LOG       
15760 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c     16  /* xFunc,
15770 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
15780 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15790 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20  URI          17 
157a0 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69   /* int */.#defi
157b0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
157c0 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38  _PCACHE2      18
157d0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
157e0 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f  che_methods2* */
157f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15800 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
15810 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74  2   19  /* sqlit
15820 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
15830 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s2* */.#define S
15840 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
15850 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
15860 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23   20  /* int */.#
15870 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15880 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20  NFIG_SQLLOG     
15890 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67    21  /* xSqllog
158a0 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69  , void* */.#defi
158b0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
158c0 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32  _MMAP_SIZE    22
158d0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74    /* sqlite3_int
158e0 36 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  64, sqlite3_int6
158f0 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  4 */.#define SQL
15900 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
15910 5f 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 32  _HEAPSIZE      2
15920 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20  3  /* int nByte 
15930 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
15940 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
15950 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72  nection Configur
15960 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
15970 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
15980 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
15990 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
159a0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
159b0 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
159c0 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
159d0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
159e0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
159f0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
15a00 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
15a10 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
15a20 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
15a30 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
15a40 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
15a50 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
15a60 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
15a70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
15a80 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
15a90 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
15aa0 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
15ab0 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
15ac0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
15ad0 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
15ae0 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
15af0 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68  all worked.  ^Th
15b00 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
15b10 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
15b20 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
15b30 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
15b40 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
15b50 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
15b60 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
15b70 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
15b80 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
15b90 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
15ba0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
15bb0 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
15bc0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
15bd0 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20  ion takes three 
15be0 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
15bf0 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
15c00 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f  ine the .** [loo
15c10 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c  kaside memory al
15c20 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75  locator] configu
15c30 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b  ration for the [
15c40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15c50 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  ion]..** ^The fi
15c60 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68  rst argument (th
15c70 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
15c80 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  r to [sqlite3_db
15c90 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a  _config()] is a.
15ca0 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20  ** pointer to a 
15cb0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f  memory buffer to
15cc0 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69   use for lookasi
15cd0 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54  de memory..** ^T
15ce0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
15cf0 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49  t after the SQLI
15d00 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
15d10 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61  ASIDE verb.** ma
15d20 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69  y be NULL in whi
15d30 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77  ch case SQLite w
15d40 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  ill allocate the
15d50 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  .** lookaside bu
15d60 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e  ffer itself usin
15d70 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  g [sqlite3_mallo
15d80 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e  c()]. ^The secon
15d90 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
15da0 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
15db0 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
15dc0 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74  er slot.  ^The t
15dd0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
15de0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
15df0 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69  * slots.  The si
15e00 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
15e10 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
15e20 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67  gument must be g
15e30 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f  reater than.** o
15e40 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70  r equal to the p
15e50 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65  roduct of the se
15e60 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61  cond and third a
15e70 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62  rguments.  The b
15e80 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65  uffer.** must be
15e90 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
15ea0 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20  -byte boundary. 
15eb0 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20   ^If the second 
15ec0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53  argument to.** S
15ed0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
15ee0 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20  OOKASIDE is not 
15ef0 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c  a multiple of 8,
15f00 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c   it is internall
15f10 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77  y.** rounded dow
15f20 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d  n to the next sm
15f30 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  aller multiple o
15f40 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b  f 8.  ^(The look
15f50 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  aside memory.** 
15f60 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
15f70 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  r a database con
15f80 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79  nection can only
15f90 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e   be changed when
15fa0 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74   that.** connect
15fb0 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65  ion is not curre
15fc0 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61  ntly using looka
15fd0 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20  side memory, or 
15fe0 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a  in other words.*
15ff0 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72  * when the "curr
16000 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72  ent value" retur
16010 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
16020 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c  e3_db_status](D,
16030 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
16040 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69  OOKASIDE],...) i
16050 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61  s zero..** Any a
16060 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65  ttempt to change
16070 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   the lookaside m
16080 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74  emory configurat
16090 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69  ion when lookasi
160a0 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20  de.** memory is 
160b0 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68  in use leaves th
160c0 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
160d0 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65  unchanged and re
160e0 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  turns .** [SQLIT
160f0 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a  E_BUSY].)^</dd>.
16100 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
16110 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
16120 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _FKEY</dt>.** <d
16130 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
16140 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
16150 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  e or disable the
16160 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a   enforcement of.
16170 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
16180 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54  constraints].  T
16190 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
161a0 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
161b0 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
161c0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
161d0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
161e0 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
161f0 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
16200 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  t,.** positive t
16210 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f  o enable FK enfo
16220 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74  rcement or negat
16230 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20  ive to leave FK 
16240 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75  enforcement.** u
16250 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73  nchanged.  The s
16260 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
16270 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
16280 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
16290 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
162a0 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
162b0 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46  dicate whether F
162c0 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73  K enforcement is
162d0 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f   off or on.** fo
162e0 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
162f0 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
16300 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
16310 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
16320 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
16330 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d   the FK enforcem
16340 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e  ent setting is n
16350 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
16360 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  . </dd>.**.** <d
16370 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
16380 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
16390 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
163a0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
163b0 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
163c0 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20  disable [CREATE 
163d0 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
163e0 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68  rs]..** There sh
163f0 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
16400 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
16410 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
16420 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
16430 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
16440 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67   to disable trig
16450 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76  gers,.** positiv
16460 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67  e to enable trig
16470 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65  gers or negative
16480 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65   to leave the se
16490 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e  tting unchanged.
164a0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
164b0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
164c0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
164d0 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
164e0 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
164f0 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
16500 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73  whether triggers
16510 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72   are disabled or
16520 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c   enabled.** foll
16530 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
16540 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
16550 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
16560 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
16570 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
16580 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69  he trigger setti
16590 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
165a0 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
165b0 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  *.** </dl>.*/.#d
165c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
165d0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
165e0 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76        1001  /* v
165f0 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a  oid* int int */.
16600 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
16610 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
16620 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a  KEY     1002  /*
16630 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
16640 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
16650 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47  NFIG_ENABLE_TRIG
16660 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e  GER  1003  /* in
16670 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a  t int* */.../*.*
16680 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
16690 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
166a0 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
166b0 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  des.**.** ^The s
166c0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
166d0 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72  result_codes() r
166e0 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
166f0 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a  r disables the.*
16700 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
16710 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
16720 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68  e of SQLite. ^Th
16730 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
16740 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64  t.** codes are d
16750 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
16760 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61  lt for historica
16770 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  l compatibility.
16780 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
16790 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
167a0 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20  codes(sqlite3*, 
167b0 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a  int onoff);../*.
167c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73  ** CAPI3REF: Las
167d0 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a  t Insert Rowid.*
167e0 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79  *.** ^Each entry
167f0 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 20   in most SQLite 
16800 74 61 62 6c 65 73 20 28 65 78 63 65 70 74 20 66  tables (except f
16810 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49  or [WITHOUT ROWI
16820 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61  D] tables).** ha
16830 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69  s a unique 64-bi
16840 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65  t signed.** inte
16850 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74  ger key called t
16860 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77  he [ROWID | "row
16870 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64  id"]. ^The rowid
16880 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c   is always avail
16890 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e  able.** as an un
168a0 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20  declared column 
168b0 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44  named ROWID, OID
168c0 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20  , or _ROWID_ as 
168d0 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a  long as those.**
168e0 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61   names are not a
168f0 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c  lso used by expl
16900 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
16910 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20  columns. ^If.** 
16920 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  the table has a 
16930 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b  column of type [
16940 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
16950 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63  KEY] then that c
16960 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74  olumn.** is anot
16970 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68  her alias for th
16980 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e  e rowid..**.** ^
16990 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  The sqlite3_last
169a0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29  _insert_rowid(D)
169b0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
169c0 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  ns the [rowid] o
169d0 66 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 72  f the .** most r
169e0 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c  ecent successful
169f0 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61   [INSERT] into a
16a00 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20   rowid table or 
16a10 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a  [virtual table].
16a20 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63  ** on database c
16a30 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20  onnection D..** 
16a40 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57  ^Inserts into [W
16a50 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61  ITHOUT ROWID] ta
16a60 62 6c 65 73 20 61 72 65 20 6e 6f 74 20 72 65 63  bles are not rec
16a70 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f  orded..** ^If no
16a80 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
16a90 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64  ERT]s into rowid
16aa0 20 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65 20   tables.** have 
16ab0 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e  ever occurred on
16ac0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
16ad0 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20  nnection D, .** 
16ae0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73  then sqlite3_las
16af0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44  t_insert_rowid(D
16b00 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
16b10 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49  **.** ^(If an [I
16b20 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69  NSERT] occurs wi
16b30 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f  thin a trigger o
16b40 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74  r within a [virt
16b50 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65  ual table].** me
16b60 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20  thod, then this 
16b70 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74  routine will ret
16b80 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  urn the [rowid] 
16b90 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a  of the inserted.
16ba0 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61  ** row as long a
16bb0 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  s the trigger or
16bc0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d   virtual table m
16bd0 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67  ethod is running
16be0 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68  ..** But once th
16bf0 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
16c00 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f  tual table metho
16c10 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75  d ends, the valu
16c20 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62  e returned .** b
16c30 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  y this routine r
16c40 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20 69  everts to what i
16c50 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65  t was before the
16c60 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
16c70 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74  ual.** table met
16c80 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a  hod began.)^.**.
16c90 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20  ** ^An [INSERT] 
16ca0 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74  that fails due t
16cb0 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  o a constraint v
16cc0 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  iolation is not 
16cd0 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  a.** successful 
16ce0 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65  [INSERT] and doe
16cf0 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
16d00 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
16d10 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  by this.** routi
16d20 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52  ne.  ^Thus INSER
16d30 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52  T OR FAIL, INSER
16d40 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53  T OR IGNORE, INS
16d50 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c  ERT OR ROLLBACK,
16d60 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f  .** and INSERT O
16d70 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20  R ABORT make no 
16d80 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72  changes to the r
16d90 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
16da0 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77  his.** routine w
16db0 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74  hen their insert
16dc0 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68  ion fails.  ^(Wh
16dd0 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  en INSERT OR REP
16de0 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  LACE.** encounte
16df0 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  rs a constraint 
16e00 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f  violation, it do
16e10 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68  es not fail.  Th
16e20 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74  e.** INSERT cont
16e30 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
16e40 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69  ion after deleti
16e50 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75  ng rows that cau
16e60 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74  sed.** the const
16e70 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f  raint problem so
16e80 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
16e90 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63  CE will always c
16ea0 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
16eb0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
16ec0 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a  s interface.)^.*
16ed0 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
16ee0 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72  rposes of this r
16ef0 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45  outine, an [INSE
16f00 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65  RT] is considere
16f10 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65  d to.** be succe
16f20 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74  ssful even if it
16f30 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79   is subsequently
16f40 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
16f50 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
16f60 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20  n is accessible 
16f70 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  to SQL statement
16f80 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61  s via the.** [la
16f90 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
16fa0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
16fb0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
16fc0 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66  rate thread perf
16fd0 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45  orms a new [INSE
16fe0 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  RT] on the same.
16ff0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
17000 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65  ection while the
17010 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
17020 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
17030 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  * function is ru
17040 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
17050 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
17060 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a  insert [rowid],.
17070 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ** then the valu
17080 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  e returned by [s
17090 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
170a0 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a  rt_rowid()] is.*
170b0 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  * unpredictable 
170c0 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
170d0 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
170e0 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
170f0 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
17100 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  wid]..*/.sqlite3
17110 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c  _int64 sqlite3_l
17120 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
17130 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
17140 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75  ** CAPI3REF: Cou
17150 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66  nt The Number Of
17160 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
17170 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
17180 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
17190 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61  number of databa
171a0 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72  se rows that wer
171b0 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20  e changed.** or 
171c0 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
171d0 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20  ted by the most 
171e0 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
171f0 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
17200 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61  .** on the [data
17210 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
17220 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
17230 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
17240 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61  r..** ^(Only cha
17250 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69  nges that are di
17260 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64  rectly specified
17270 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d   by the [INSERT]
17280 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f  , [UPDATE],.** o
17290 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
172a0 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64  ment are counted
172b0 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61  .  Auxiliary cha
172c0 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a  nges caused by.*
172d0 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66  * triggers or [f
172e0 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
172f0 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  ns] are not coun
17300 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a  ted.)^ Use the.*
17310 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  * [sqlite3_total
17320 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63  _changes()] func
17330 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65  tion to find the
17340 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
17350 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c   changes.** incl
17360 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61  uding changes ca
17370 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73  used by triggers
17380 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79   and foreign key
17390 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   actions..**.** 
173a0 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69  ^Changes to a vi
173b0 65 77 20 74 68 61 74 20 61 72 65 20 73 69 6d 75  ew that are simu
173c0 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53  lated by an [INS
173d0 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d  TEAD OF trigger]
173e0 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  .** are not coun
173f0 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20  ted.  Only real 
17400 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72  table changes ar
17410 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a  e counted..**.**
17420 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65   ^(A "row change
17430 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f  " is a change to
17440 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66   a single row of
17450 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a   a single table.
17460 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20  ** caused by an 
17470 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20  INSERT, DELETE, 
17480 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d  or UPDATE statem
17490 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a  ent.  Rows that.
174a0 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61  ** are changed a
174b0 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f  s side effects o
174c0 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  f [REPLACE] cons
174d0 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
174e0 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20  n,.** rollback, 
174f0 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
17500 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20  , [DROP TABLE], 
17510 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a  or by any other.
17520 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f  ** mechanisms do
17530 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69   not count as di
17540 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
17550 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69  .)^.**.** A "tri
17560 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73  gger context" is
17570 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63   a scope of exec
17580 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e  ution that begin
17590 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69  s and.** ends wi
175a0 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66  th the script of
175b0 20 61 20 5b 43 52 45 41 54 45 20 54 52 49 47 47   a [CREATE TRIGG
175c0 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a  ER | trigger]. .
175d0 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74  ** Most SQL stat
175e0 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76  ements are.** ev
175f0 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20  aluated outside 
17600 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20  of any trigger. 
17610 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f   This is the "to
17620 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67  p level".** trig
17630 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66  ger context.  If
17640 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73   a trigger fires
17650 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65   from the top le
17660 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72  vel, a.** new tr
17670 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73  igger context is
17680 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65   entered for the
17690 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61   duration of tha
176a0 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72  t one.** trigger
176b0 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63  .  Subtriggers c
176c0 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74  reate subcontext
176d0 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61  s for their dura
176e0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  tion..**.** ^Cal
176f0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78  ling [sqlite3_ex
17700 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ec()] or [sqlite
17710 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73  3_step()] recurs
17720 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ively does.** no
17730 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74  t create a new t
17740 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
17750 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
17760 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
17770 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63   number of direc
17780 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e  t row changes in
17790 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63   the.** most rec
177a0 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ent INSERT, UPDA
177b0 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74  TE, or DELETE st
177c0 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
177d0 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67  he same.** trigg
177e0 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  er context..**.*
177f0 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61  * ^Thus, when ca
17800 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f  lled from the to
17810 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75  p level, this fu
17820 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
17830 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
17840 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
17850 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
17860 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
17870 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73  LETE.** that als
17880 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68  o occurred at th
17890 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28  e top level.  ^(
178a0 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20  Within the body 
178b0 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a  of a trigger,.**
178c0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
178d0 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65  nges() interface
178e0 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74   can be called t
178f0 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
17900 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20  r of.** changes 
17910 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
17920 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49  ntly completed I
17930 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
17940 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74  r DELETE.** stat
17950 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
17960 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d   body of the sam
17970 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f  e trigger..** Ho
17980 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65  wever, the numbe
17990 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20  r returned does 
179a0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e  not include chan
179b0 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79  ges.** caused by
179c0 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e   subtriggers sin
179d0 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68  ce those have th
179e0 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e  eir own context.
179f0 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
17a00 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  o the [sqlite3_t
17a10 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
17a20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
17a30 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
17a40 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
17a50 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
17a60 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
17a70 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
17a80 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
17a90 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
17aa0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
17ab0 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
17ac0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
17ad0 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
17ae0 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
17af0 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65  rned.** is unpre
17b00 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
17b10 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
17b20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
17b30 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
17b40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17b50 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
17b60 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
17b70 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
17b80 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
17b90 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61  umber of row cha
17ba0 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b  nges caused by [
17bb0 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44  INSERT],.** [UPD
17bc0 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ATE] or [DELETE]
17bd0 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63   statements sinc
17be0 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  e the [database 
17bf0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20  connection] was 
17c00 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65  opened..** ^(The
17c10 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20   count returned 
17c20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  by sqlite3_total
17c30 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75  _changes() inclu
17c40 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a  des all changes.
17c50 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45  ** from all [CRE
17c60 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
17c70 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20  igger] contexts 
17c80 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65  and changes made
17c90 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20   by.** [foreign 
17ca0 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f  key actions]. Ho
17cb0 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f  wever,.** the co
17cc0 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
17cd0 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65  lude changes use
17ce0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b  d to implement [
17cf0 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
17d00 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c  ints,.** do roll
17d10 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70  backs or ABORT p
17d20 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44  rocessing, or [D
17d30 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65  ROP TABLE] proce
17d40 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63  ssing.  The.** c
17d50 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ount does not in
17d60 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69  clude rows of vi
17d70 65 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e  ews that fire an
17d80 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
17d90 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68  gger],.** though
17da0 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20   if the INSTEAD 
17db0 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73  OF trigger makes
17dc0 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20   changes of its 
17dd0 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67  own, those chang
17de0 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74  es .** are count
17df0 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71  ed.)^.** ^The sq
17e00 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
17e10 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  ges() function c
17e20 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65  ounts the change
17e30 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20  s as soon as.** 
17e40 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68  the statement th
17e50 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73  at makes them is
17e60 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e   completed (when
17e70 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
17e80 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73  andle.** is pass
17e90 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ed to [sqlite3_r
17ea0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
17eb0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29  te3_finalize()])
17ec0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
17ed0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
17ee0 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
17ef0 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
17f00 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
17f10 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61  ], and the [tota
17f20 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  l_changes() SQL 
17f30 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
17f40 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
17f50 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
17f60 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
17f70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17f80 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
17f90 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
17fa0 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
17fb0 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
17fc0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20  .** returned is 
17fd0 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
17fe0 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
17ff0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
18000 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73  _total_changes(s
18010 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
18020 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72   CAPI3REF: Inter
18030 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e  rupt A Long-Runn
18040 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20  ing Query.**.** 
18050 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63  ^This function c
18060 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e  auses any pendin
18070 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  g database opera
18080 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e  tion to abort an
18090 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69  d.** return at i
180a0 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f  ts earliest oppo
180b0 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f  rtunity. This ro
180c0 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c  utine is typical
180d0 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20  ly.** called in 
180e0 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73  response to a us
180f0 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61  er action such a
18100 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63  s pressing "Canc
18110 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43  el".** or Ctrl-C
18120 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20   where the user 
18130 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65  wants a long que
18140 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  ry operation to 
18150 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74  halt.** immediat
18160 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69  ely..**.** ^It i
18170 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  s safe to call t
18180 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d  his routine from
18190 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72   a thread differ
181a0 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20  ent from the.** 
181b0 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63  thread that is c
181c0 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
181d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70   the database op
181e0 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74  eration.  But it
181f0 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20  .** is not safe 
18200 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
18210 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74  tine with a [dat
18220 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18230 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f  ] that.** is clo
18240 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f  sed or might clo
18250 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65  se before sqlite
18260 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65  3_interrupt() re
18270 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  turns..**.** ^If
18280 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f   an SQL operatio
18290 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79  n is very nearly
182a0 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65   finished at the
182b0 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71   time when.** sq
182c0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
182d0 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65  ) is called, the
182e0 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68  n it might not h
182f0 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69  ave an opportuni
18300 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65  ty.** to be inte
18310 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68  rrupted and migh
18320 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f  t continue to co
18330 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  mpletion..**.** 
18340 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ^An SQL operatio
18350 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72  n that is interr
18360 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72  upted will retur
18370 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  n [SQLITE_INTERR
18380 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  UPT]..** ^If the
18390 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c   interrupted SQL
183a0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e   operation is an
183b0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
183c0 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68   or DELETE.** th
183d0 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20  at is inside an 
183e0 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
183f0 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65  tion, then the e
18400 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f  ntire transactio
18410 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c  n.** will be rol
18420 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74  led back automat
18430 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ically..**.** ^T
18440 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
18450 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20  rupt(D) call is 
18460 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20  in effect until 
18470 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75  all currently ru
18480 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
18490 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61  tements on [data
184a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
184b0 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41   D complete.  ^A
184c0 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65  ny new SQL state
184d0 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
184e0 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
184f0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
18500 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64  rrupt() call and
18510 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20   before the .** 
18520 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
18530 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  ts reaches zero 
18540 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  are interrupted 
18550 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62  as if they had b
18560 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70  een.** running p
18570 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69  rior to the sqli
18580 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
18590 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20  call.  ^New SQL 
185a0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
185b0 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
185c0 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67  fter the running
185d0 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74   statement count
185e0 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
185f0 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65  e.** not effecte
18600 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
18610 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a  _interrupt()..**
18620 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69   ^A call to sqli
18630 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
18640 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65   that occurs whe
18650 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72  n there are no r
18660 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
18670 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f  atements is a no
18680 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65  -op and has no e
18690 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61  ffect on SQL sta
186a0 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
186b0 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
186c0 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
186d0 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72  terrupt() call r
186e0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66  eturns..**.** If
186f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
18700 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20  nnection closes 
18710 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69  while [sqlite3_i
18720 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69  nterrupt()].** i
18730 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62  s running then b
18740 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c  ad things will l
18750 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f  ikely happen..*/
18760 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e  .void sqlite3_in
18770 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a  terrupt(sqlite3*
18780 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
18790 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
187a0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
187b0 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a  t Is Complete.**
187c0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
187d0 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75  es are useful du
187e0 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e  ring command-lin
187f0 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72  e input to deter
18800 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63  mine if the.** c
18810 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64  urrently entered
18820 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66   text seems to f
18830 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53  orm a complete S
18840 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a  QL statement or.
18850 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c  ** if additional
18860 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64   input is needed
18870 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20   before sending 
18880 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a  the text into.**
18890 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73   SQLite for pars
188a0 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ing.  ^These rou
188b0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69  tines return 1 i
188c0 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  f the input stri
188d0 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f  ng.** appears to
188e0 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53   be a complete S
188f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  QL statement.  ^
18900 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a  A statement is j
18910 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63  udged to be.** c
18920 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e  omplete if it en
18930 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f  ds with a semico
18940 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73  lon token and is
18950 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66   not a prefix of
18960 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65   a.** well-forme
18970 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52  d CREATE TRIGGER
18980 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65   statement.  ^Se
18990 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72  micolons that ar
189a0 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69  e embedded withi
189b0 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65  n.** string lite
189c0 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69  rals or quoted i
189d0 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20  dentifier names 
189e0 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20  or comments are 
189f0 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65  not.** independe
18a00 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20  nt tokens (they 
18a10 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20  are part of the 
18a20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74  token in which t
18a30 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64  hey are.** embed
18a40 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f  ded) and thus do
18a50 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20   not count as a 
18a60 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e  statement termin
18a70 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61  ator.  ^Whitespa
18a80 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e  ce.** and commen
18a90 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74  ts that follow t
18aa0 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c  he final semicol
18ab0 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a  on are ignored..
18ac0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
18ad0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69  tines return 0 i
18ae0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
18af0 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20  is incomplete.  
18b00 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ^If a.** memory 
18b10 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73  allocation fails
18b20 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f  , then SQLITE_NO
18b30 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  MEM is returned.
18b40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
18b50 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61  utines do not pa
18b60 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74  rse the SQL stat
18b70 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77  ements thus.** w
18b80 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73  ill not detect s
18b90 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63  yntactically inc
18ba0 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a  orrect SQL..**.*
18bb0 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61  * ^(If SQLite ha
18bc0 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69  s not been initi
18bd0 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71  alized using [sq
18be0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
18bf0 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f  ()] prior .** to
18c00 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65   invoking sqlite
18c10 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74  3_complete16() t
18c20 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  hen sqlite3_init
18c30 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
18c40 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63  ked.** automatic
18c50 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
18c60 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49  complete16().  I
18c70 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a  f that initializ
18c80 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20  ation fails,.** 
18c90 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
18ca0 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
18cb0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
18cc0 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f  will be non-zero
18cd0 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f  .** regardless o
18ce0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
18cf0 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69   the input SQL i
18d00 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a  s complete.)^.**
18d10 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
18d20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
18d30 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  te()] must be a 
18d40 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
18d50 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e  ** UTF-8 string.
18d60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
18d70 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
18d80 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20  plete16()] must 
18d90 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
18da0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
18db0 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
18dc0 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69  byte order..*/.i
18dd0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
18de0 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ete(const char *
18df0 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  sql);.int sqlite
18e00 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e  3_complete16(con
18e10 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a  st void *sql);..
18e20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18e30 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62  Register A Callb
18e40 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51  ack To Handle SQ
18e50 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73  LITE_BUSY Errors
18e60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
18e70 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
18e80 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20  (D,X,P) routine 
18e90 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  sets a callback 
18ea0 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68  function X.** th
18eb0 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  at might be invo
18ec0 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e  ked with argumen
18ed0 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20  t P whenever.** 
18ee0 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
18ef0 64 65 20 74 6f 20 61 63 63 65 73 73 20 61 20 64  de to access a d
18f00 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 73  atabase table as
18f10 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a  sociated with.**
18f20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
18f30 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e  ction] D when an
18f40 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20  other thread.** 
18f50 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 74  or process has t
18f60 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e  he table locked.
18f70 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
18f80 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69  busy_handler() i
18f90 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
18fa0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a   to implement.**
18fb0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
18fc0 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50  imeout()] and [P
18fd0 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f  RAGMA busy_timeo
18fe0 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ut]..**.** ^If t
18ff0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
19000 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b   is NULL, then [
19010 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
19020 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
19030 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63  diately upon enc
19040 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f  ountering the lo
19050 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73  ck.  ^If the bus
19060 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  y callback.** is
19070 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20   not NULL, then 
19080 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67  the callback mig
19090 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ht be invoked wi
190a0 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  th two arguments
190b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
190c0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
190d0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
190e0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
190f0 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77   void* pointer w
19100 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74  hich.** is the t
19110 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
19120 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
19130 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73  ndler().  ^The s
19140 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
19150 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61  o.** the busy ha
19160 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  ndler callback i
19170 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
19180 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62  times that the b
19190 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a  usy handler has.
191a0 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20  ** been invoked 
191b0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63  for the same loc
191c0 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  king event.  ^If
191d0 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c   the.** busy cal
191e0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c  lback returns 0,
191f0 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f   then no additio
19200 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65  nal attempts are
19210 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65   made to.** acce
19220 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
19230 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  and [SQLITE_BUSY
19240 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ] is returned.**
19250 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
19260 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ion..** ^If the 
19270 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
19280 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
19290 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a  another attempt.
192a0 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63  ** is made to ac
192b0 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
192c0 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20  e and the cycle 
192d0 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  repeats..**.** T
192e0 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61  he presence of a
192f0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f   busy handler do
19300 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  es not guarantee
19310 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65   that it will be
19320 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e   invoked.** when
19330 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63   there is lock c
19340 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53  ontention. ^If S
19350 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73  QLite determines
19360 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74   that invoking t
19370 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c  he busy.** handl
19380 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20  er could result 
19390 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69  in a deadlock, i
193a0 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20  t will go ahead 
193b0 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  and return [SQLI
193c0 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74  TE_BUSY].** to t
193d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
193e0 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69  nstead of invoki
193f0 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20  ng the .** busy 
19400 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73  handler..** Cons
19410 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20  ider a scenario 
19420 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73  where one proces
19430 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
19440 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a  ead lock that.**
19450 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f   it is trying to
19460 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65   promote to a re
19470 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a  served lock and.
19480 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63  ** a second proc
19490 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
194a0 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74   reserved lock t
194b0 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67  hat it is trying
194c0 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
194d0 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c  o an exclusive l
194e0 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20  ock.  The first 
194f0 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70  process cannot p
19500 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73  roceed.** becaus
19510 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
19520 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  by the second an
19530 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  d the second pro
19540 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70  cess cannot.** p
19550 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69  roceed because i
19560 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
19570 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62  the first.  If b
19580 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a  oth processes.**
19590 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79   invoke the busy
195a0 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68   handlers, neith
195b0 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79  er will make any
195c0 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72   progress.  Ther
195d0 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65  efore,.** SQLite
195e0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
195f0 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66  _BUSY] for the f
19600 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f  irst process, ho
19610 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a  ping that this.*
19620 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68  * will induce th
19630 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
19640 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72  to release its r
19650 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c  ead lock and all
19660 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  ow.** the second
19670 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63   process to proc
19680 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
19690 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c  default busy cal
196a0 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a  lback is NULL..*
196b0 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
196c0 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
196d0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
196e0 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
196f0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
19700 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
19710 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
19720 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
19730 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
19740 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e  et handler.)^  ^
19750 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
19760 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
19770 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72  timeout()].** or
19780 20 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41   evaluating [PRA
19790 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
197a0 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20  =N] will change 
197b0 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64  the.** busy hand
197c0 6c 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65  ler and thus cle
197d0 61 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c  ar any previousl
197e0 79 20 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c  y set busy handl
197f0 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75  er..**.** The bu
19800 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  sy callback shou
19810 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20  ld not take any 
19820 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f  actions which mo
19830 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61  dify the.** data
19840 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
19850 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
19860 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20   busy handler.  
19870 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a  In other words,.
19880 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
19890 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ler is not reent
198a0 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20  rant.  Any such 
198b0 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c  actions.** resul
198c0 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  t in undefined b
198d0 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20  ehavior..** .** 
198e0 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  A busy handler m
198f0 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
19900 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
19910 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65  ction.** or [pre
19920 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
19930 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
19940 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
19950 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
19960 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
19970 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
19980 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b  d*,int), void*);
19990 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
199a0 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d  : Set A Busy Tim
199b0 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  eout.**.** ^This
199c0 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
199d0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
199e0 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e  ndler | busy han
199f0 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70  dler] that sleep
19a00 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69  s.** for a speci
19a10 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74  fied amount of t
19a20 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65  ime when a table
19a30 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68   is locked.  ^Th
19a40 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c  e handler.** wil
19a50 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65  l sleep multiple
19a60 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20   times until at 
19a70 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
19a80 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
19a90 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75  ing.** have accu
19aa0 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72  mulated.  ^After
19ab0 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
19ac0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
19ad0 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  leeping,.** the 
19ae0 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20  handler returns 
19af0 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b  0 which causes [
19b00 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
19b10 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  to return.** [SQ
19b20 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a  LITE_BUSY]..**.*
19b30 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20  * ^Calling this 
19b40 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20  routine with an 
19b50 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68  argument less th
19b60 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
19b70 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66  ero.** turns off
19b80 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65   all busy handle
19b90 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  rs..**.** ^(Ther
19ba0 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
19bb0 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
19bc0 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63  ler for a partic
19bd0 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
19be0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
19bf0 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65  y any given mome
19c00 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20  nt.  If another 
19c10 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  busy handler.** 
19c20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73  was defined  (us
19c30 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
19c40 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72  y_handler()]) pr
19c50 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  ior to calling.*
19c60 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  * this routine, 
19c70 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20  that other busy 
19c80 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72  handler is clear
19c90 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ed.)^.**.** See 
19ca0 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62  also:  [PRAGMA b
19cb0 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a  usy_timeout].*/.
19cc0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
19cd0 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33  _timeout(sqlite3
19ce0 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a  *, int ms);../*.
19cf0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
19d00 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65  venience Routine
19d10 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75  s For Running Qu
19d20 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73  eries.**.** This
19d30 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74   is a legacy int
19d40 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70  erface that is p
19d50 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63  reserved for bac
19d60 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
19d70 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20  lity..** Use of 
19d80 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  this interface i
19d90 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65  s not recommende
19da0 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74  d..**.** Definit
19db0 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74  ion: A <b>result
19dc0 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65   table</b> is me
19dd0 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74  mory data struct
19de0 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74  ure created by t
19df0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  he.** [sqlite3_g
19e00 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65  et_table()] inte
19e10 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74  rface.  A result
19e20 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74   table records t
19e30 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71  he.** complete q
19e40 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f  uery results fro
19e50 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75  m one or more qu
19e60 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eries..**.** The
19e70 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61   table conceptua
19e80 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72  lly has a number
19e90 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c   of rows and col
19ea0 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68  umns.  But.** th
19eb0 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20  ese numbers are 
19ec0 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20  not part of the 
19ed0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73  result table its
19ee0 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e  elf.  These.** n
19ef0 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69  umbers are obtai
19f00 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20  ned separately. 
19f10 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75   Let N be the nu
19f20 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20  mber of rows.** 
19f30 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d  and M be the num
19f40 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a  ber of columns..
19f50 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
19f60 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79  able is an array
19f70 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
19f80 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
19f90 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a  UTF-8 strings..*
19fa0 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31  * There are (N+1
19fb0 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20  )*M elements in 
19fc0 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20  the array.  The 
19fd0 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73  first M pointers
19fe0 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72   point.** to zer
19ff0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
1a000 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61  ings that  conta
1a010 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  in the names of 
1a020 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20  the columns..** 
1a030 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e  The remaining en
1a040 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20  tries all point 
1a050 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  to query results
1a060 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72  .  NULL values r
1a070 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c  esult.** in NULL
1a080 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20   pointers.  All 
1a090 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65  other values are
1a0a0 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20   in their UTF-8 
1a0b0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
1a0c0 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73  ** string repres
1a0d0 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75  entation as retu
1a0e0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
1a0f0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e  _column_text()].
1a100 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
1a110 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73  table might cons
1a120 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ist of one or mo
1a130 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  re memory alloca
1a140 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20  tions..** It is 
1a150 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73  not safe to pass
1a160 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
1a170 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c  directly to [sql
1a180 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
1a190 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1a1a0 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f  should be deallo
1a1b0 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cated using [sql
1a1c0 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1a1d0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61  )]..**.** ^(As a
1a1e0 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65  n example of the
1a1f0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f   result table fo
1a200 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20  rmat, suppose a 
1a210 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20  query result.** 
1a220 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
1a230 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1a240 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
1a250 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41   Name        | A
1a260 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d  ge.**        ---
1a270 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1a280 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41  ----.**        A
1a290 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a  lice       | 43.
1a2a0 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20  **        Bob   
1a2b0 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20        | 28.**   
1a2c0 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20       Cindy      
1a2d0 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c   | 21.** </pre><
1a2e0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1a2f0 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f  ** There are two
1a300 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61   column (M==2) a
1a310 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e  nd three rows (N
1a320 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a  ==3).  Thus the.
1a330 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  ** result table 
1a340 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20  has 8 entries.  
1a350 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75  Suppose the resu
1a360 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72  lt table is stor
1a370 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61  ed.** in an arra
1a380 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74  y names azResult
1a390 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74  .  Then azResult
1a3a0 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74   holds this cont
1a3b0 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ent:.**.** <bloc
1a3c0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1a3d0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1a3e0 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b  #91;0] = "Name";
1a3f0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1a400 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67  ult&#91;1] = "Ag
1a410 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1a420 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20  Result&#91;2] = 
1a430 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20  "Alice";.**     
1a440 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1a450 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20  3] = "43";.**   
1a460 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1a470 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a  1;4] = "Bob";.**
1a480 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1a490 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a  &#91;5] = "28";.
1a4a0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1a4b0 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e  lt&#91;6] = "Cin
1a4c0 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  dy";.**        a
1a4d0 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d  zResult&#91;7] =
1a4e0 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   "21";.** </pre>
1a4f0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
1a500 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1a510 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66  e3_get_table() f
1a520 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65  unction evaluate
1a530 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  s one or more.**
1a540 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72   semicolon-separ
1a550 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
1a560 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d  nts in the zero-
1a570 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
1a580 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74  .** string of it
1a590 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  s 2nd parameter 
1a5a0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65  and returns a re
1a5b0 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68  sult table to th
1a5c0 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76  e.** pointer giv
1a5d0 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61  en in its 3rd pa
1a5e0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  rameter..**.** A
1a5f0 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61  fter the applica
1a600 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65  tion has finishe
1a610 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c  d with the resul
1a620 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67  t from sqlite3_g
1a630 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69  et_table(),.** i
1a640 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20  t must pass the 
1a650 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69  result table poi
1a660 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
1a670 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20  free_table() in 
1a680 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65  order to.** rele
1a690 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74  ase the memory t
1a6a0 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64  hat was malloced
1a6b0 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  .  Because of th
1a6c0 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71  e way the.** [sq
1a6d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1a6e0 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73  happens within s
1a6f0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1a700 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a  (), the calling.
1a710 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
1a720 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c   not try to call
1a730 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1a740 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c  ] directly.  Onl
1a750 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  y.** [sqlite3_fr
1a760 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61  ee_table()] is a
1a770 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74  ble to release t
1a780 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72  he memory proper
1a790 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a  ly and safely..*
1a7a0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1a7b0 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74  _get_table() int
1a7c0 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d  erface is implem
1a7d0 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70  ented as a wrapp
1a7e0 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
1a7f0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20  lite3_exec()].  
1a800 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1a810 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20  table() routine 
1a820 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63  does not have ac
1a830 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69  cess.** to any i
1a840 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72  nternal data str
1a850 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74  uctures of SQLit
1a860 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79  e.  It uses only
1a870 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69   the public.** i
1a880 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64  nterface defined
1a890 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e   here.  As a con
1a8a0 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73  sequence, errors
1a8b0 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74   that occur in t
1a8c0 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61  he.** wrapper la
1a8d0 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74  yer outside of t
1a8e0 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c  he internal [sql
1a8f0 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c  ite3_exec()] cal
1a900 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66  l are not.** ref
1a910 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71  lected in subseq
1a920 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
1a930 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1a940 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
1a950 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69  _errmsg()]..*/.i
1a960 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  nt sqlite3_get_t
1a970 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20  able(.  sqlite3 
1a980 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
1a990 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
1a9a0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1a9b0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20  r *zSql,     /* 
1a9c0 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
1a9d0 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ted */.  char **
1a9e0 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f  *pazResult,    /
1a9f0 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65  * Results of the
1aa00 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20   query */.  int 
1aa10 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20  *pnRow,         
1aa20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
1aa30 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74  esult rows writt
1aa40 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74  en here */.  int
1aa50 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20   *pnColumn,     
1aa60 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
1aa70 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77  result columns w
1aa80 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
1aa90 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67   char **pzErrmsg
1aaa0 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
1aab0 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
1aac0 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69   */.);.void sqli
1aad0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63  te3_free_table(c
1aae0 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a  har **result);..
1aaf0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1ab00 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67  Formatted String
1ab10 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69   Printing Functi
1ab20 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
1ab30 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72  routines are wor
1ab40 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20  k-alikes of the 
1ab50 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c  "printf()" famil
1ab60 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  y of functions.*
1ab70 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  * from the stand
1ab80 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
1ab90 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1aba0 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
1abb0 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
1abc0 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74  () routines writ
1abd0 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c  e their.** resul
1abe0 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  ts into memory o
1abf0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
1ac00 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
1ac10 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20  .** The strings 
1ac20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
1ac30 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73  e two routines s
1ac40 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65  hould be.** rele
1ac50 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ased by [sqlite3
1ac60 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68  _free()].  ^Both
1ac70 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1ac80 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
1ac90 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d  er if [sqlite3_m
1aca0 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62  alloc()] is unab
1acb0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65  le to allocate e
1acc0 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20  nough.** memory 
1acd0 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
1ace0 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a  lting string..**
1acf0 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
1ad00 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  3_snprintf() rou
1ad10 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
1ad20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20  to "snprintf()" 
1ad30 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
1ad40 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20  dard C library. 
1ad50 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77   The result is w
1ad60 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a  ritten into the.
1ad70 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69  ** buffer suppli
1ad80 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
1ad90 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65   parameter whose
1ada0 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62   size is given b
1adb0 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  y.** the first p
1adc0 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74  arameter. Note t
1add0 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66  hat the order of
1ade0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77   the.** first tw
1adf0 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  o parameters is 
1ae00 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e  reversed from sn
1ae10 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69  printf().)^  Thi
1ae20 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f  s is an.** histo
1ae30 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74  rical accident t
1ae40 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69  hat cannot be fi
1ae50 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  xed without brea
1ae60 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64  king.** backward
1ae70 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
1ae80 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68    ^(Note also th
1ae90 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
1aea0 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
1aeb0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
1aec0 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
1aed0 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
1aee0 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
1aef0 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
1af00 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
1af10 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68  .)^  We admit th
1af20 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  at.** the number
1af30 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77   of characters w
1af40 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20  ritten would be 
1af50 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65  a more useful re
1af60 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75  turn.** value bu
1af70 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e  t we cannot chan
1af80 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ge the implement
1af90 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
1afa0 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e  _snprintf().** n
1afb0 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ow without break
1afc0 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ing compatibilit
1afd0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e  y..**.** ^As lon
1afe0 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
1aff0 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
1b000 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
1b010 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1b020 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
1b030 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
1b040 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
1b050 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72  nated.  ^The fir
1b060 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
1b070 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c  "n" is the total
1b080 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
1b090 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73  fer, including s
1b0a0 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  pace for.** the 
1b0b0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
1b0c0 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74    So the longest
1b0d0 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e   string that can
1b0e0 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a   be completely.*
1b0f0 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62  * written will b
1b100 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73  e n-1 characters
1b110 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1b120 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29  ite3_vsnprintf()
1b130 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61   routine is a va
1b140 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66  rargs version of
1b150 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1b160 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  f()..**.** These
1b170 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d   routines all im
1b180 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64  plement some add
1b190 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69  itional formatti
1b1a0 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68  ng.** options th
1b1b0 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  at are useful fo
1b1c0 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53  r constructing S
1b1d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
1b1e0 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75  * All of the usu
1b1f0 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d  al printf() form
1b200 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61  atting options a
1b210 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69  pply.  In additi
1b220 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20  on, there.** is 
1b230 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20  are "%q", "%Q", 
1b240 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73  and "%z" options
1b250 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71  ..**.** ^(The %q
1b260 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1b270 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74  ke %s in that it
1b280 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e   substitutes a n
1b290 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ul-terminated.**
1b2a0 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65   string from the
1b2b0 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20   argument list. 
1b2c0 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75   But %q also dou
1b2d0 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20  bles every '\'' 
1b2e0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71  character..** %q
1b2f0 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72   is designed for
1b300 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74   use inside a st
1b310 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20  ring literal.)^ 
1b320 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63   By doubling eac
1b330 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63  h '\''.** charac
1b340 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74  ter it escapes t
1b350 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e  hat character an
1b360 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62  d allows it to b
1b370 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a  e inserted into.
1b380 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a  ** the string..*
1b390 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65  *.** For example
1b3a0 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72  , assume the str
1b3b0 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65  ing variable zTe
1b3c0 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74  xt contains text
1b3d0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1b3e0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1b3f0 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1b400 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68  Text = "It's a h
1b410 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c  appy day!";.** <
1b420 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1b430 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e  e>.**.** One can
1b440 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69   use this text i
1b450 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
1b460 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  nt as follows:.*
1b470 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1b480 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1b490 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
1b4a0 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
1b4b0 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
1b4c0 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29  S('%q')", zText)
1b4d0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
1b4e0 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
1b4f0 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
1b500 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
1b510 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1b520 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61  uote>.**.** Beca
1b530 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61  use the %q forma
1b540 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64  t string is used
1b550 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61  , the '\'' chara
1b560 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a  cter in zText.**
1b570 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20   is escaped and 
1b580 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65  the SQL generate
1b590 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  d is as follows:
1b5a0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1b5b0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1b5c0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1b5d0 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20  VALUES('It''s a 
1b5e0 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20  happy day!').** 
1b5f0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1b600 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te>.**.** This i
1b610 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20  s correct.  Had 
1b620 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65  we used %s inste
1b630 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65  ad of %q, the ge
1b640 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77  nerated SQL.** w
1b650 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64  ould have looked
1b660 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
1b670 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1b680 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
1b690 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
1b6a0 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20  S('It's a happy 
1b6b0 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65  day!');.** </pre
1b6c0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1b6d0 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64  *.** This second
1b6e0 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53   example is an S
1b6f0 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e  QL syntax error.
1b700 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72    As a general r
1b710 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a  ule you should.*
1b720 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20  * always use %q 
1b730 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68  instead of %s wh
1b740 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78  en inserting tex
1b750 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20  t into a string 
1b760 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  literal..**.** ^
1b770 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77  (The %Q option w
1b780 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63  orks like %q exc
1b790 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73  ept it also adds
1b7a0 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61   single quotes a
1b7b0 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74  round.** the out
1b7c0 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61  side of the tota
1b7d0 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74  l string.  Addit
1b7e0 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20  ionally, if the 
1b7f0 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
1b800 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  .** argument lis
1b810 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
1b820 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75  ter, %Q substitu
1b830 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55  tes the text "NU
1b840 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20  LL" (without.** 
1b850 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29  single quotes).)
1b860 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70  ^  So, for examp
1b870 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61  le, one could sa
1b880 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  y:.**.** <blockq
1b890 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1b8a0 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
1b8b0 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
1b8c0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
1b8d0 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78  ALUES(%Q)", zTex
1b8e0 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
1b8f0 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
1b900 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
1b910 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
1b920 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1b930 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1b940 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c  e code above wil
1b950 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65  l render a corre
1b960 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ct SQL statement
1b970 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20   in the zSQL.** 
1b980 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66  variable even if
1b990 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61   the zText varia
1b9a0 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ble is a NULL po
1b9b0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  inter..**.** ^(T
1b9c0 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
1b9d0 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
1b9e0 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69  like "%s" but wi
1b9f0 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
1ba00 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
1ba10 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
1ba20 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
1ba30 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
1ba40 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
1ba50 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
1ba60 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
1ba70 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20  ring.)^.*/.char 
1ba80 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  *sqlite3_mprintf
1ba90 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
1baa0 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1bab0 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  _vmprintf(const 
1bac0 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1bad0 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73  .char *sqlite3_s
1bae0 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1baf0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
1bb00 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
1bb10 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74  e3_vsnprintf(int
1bb20 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
1bb30 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f  r*, va_list);../
1bb40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
1bb50 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
1bb60 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a   Subsystem.**.**
1bb70 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
1bb80 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65   uses these thre
1bb90 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61  e routines for a
1bba0 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a  ll of its own.**
1bbb0 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79   internal memory
1bbc0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
1bbd0 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65  s. "Core" in the
1bbe0 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
1bbf0 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69  ce.** does not i
1bc00 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67  nclude operating
1bc10 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
1bc20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
1bc30 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e  ion.  The.** Win
1bc40 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61  dows VFS uses na
1bc50 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  tive malloc() an
1bc60 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d  d free() for som
1bc70 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  e operations..**
1bc80 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1bc90 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
1bca0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
1bcb0 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
1bcc0 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
1bcd0 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1bce0 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
1bcf0 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
1bd00 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1bd10 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61  _malloc() is una
1bd20 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75  ble to obtain su
1bd30 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a  fficient free.**
1bd40 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75   memory, it retu
1bd50 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
1bd60 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72  er.  ^If the par
1bd70 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73  ameter N to.** s
1bd80 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1bd90 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74  is zero or negat
1bda0 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ive then sqlite3
1bdb0 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  _malloc() return
1bdc0 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
1bdd0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ter..**.** ^Call
1bde0 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
1bdf0 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  () with a pointe
1be00 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  r previously ret
1be10 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
1be20 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
1be30 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1be40 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20  ) releases that 
1be50 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61  memory so.** tha
1be60 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65  t it might be re
1be70 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  used.  ^The sqli
1be80 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69  te3_free() routi
1be90 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70  ne is.** a no-op
1bea0 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69   if is called wi
1beb0 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
1bec0 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55  r.  Passing a NU
1bed0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f  LL pointer.** to
1bee0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1bef0 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66  is harmless.  Af
1bf00 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c  ter being freed,
1bf10 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c   memory.** shoul
1bf20 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61  d neither be rea
1bf30 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20  d nor written.  
1bf40 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65  Even reading pre
1bf50 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a  viously freed.**
1bf60 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65   memory might re
1bf70 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e  sult in a segmen
1bf80 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20  tation fault or 
1bf90 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
1bfa0 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f  or..** Memory co
1bfb0 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d  rruption, a segm
1bfc0 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20  entation fault, 
1bfd0 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
1bfe0 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72  error.** might r
1bff0 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33  esult if sqlite3
1c000 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65  _free() is calle
1c010 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  d with a non-NUL
1c020 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a  L pointer that.*
1c030 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e  * was not obtain
1c040 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
1c050 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
1c060 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
1c070 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
1c080 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74  e3_realloc() int
1c090 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
1c0a0 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70  to resize a.** p
1c0b0 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rior memory allo
1c0c0 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20  cation to be at 
1c0d0 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77  least N bytes, w
1c0e0 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a  here N is the.**
1c0f0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1c100 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61  r.  The memory a
1c110 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20  llocation to be 
1c120 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66  resized is the f
1c130 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
1c140 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69  r.)^ ^ If the fi
1c150 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
1c160 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1c170 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  ().** is a NULL 
1c180 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73  pointer then its
1c190 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65   behavior is ide
1c1a0 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e  ntical to callin
1c1b0 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  g.** sqlite3_mal
1c1c0 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69  loc(N) where N i
1c1d0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
1c1e0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1c1f0 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20  3_realloc()..** 
1c200 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70  ^If the second p
1c210 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1c220 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73  te3_realloc() is
1c230 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61   zero or.** nega
1c240 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65  tive then the be
1c250 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c  havior is exactl
1c260 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61  y the same as ca
1c270 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
1c280 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50  _free(P) where P
1c290 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
1c2a0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1c2b0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
1c2c0 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   ^sqlite3_reallo
1c2d0 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  c() returns a po
1c2e0 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
1c2f0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
1c300 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  of at least N by
1c310 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e  tes in size or N
1c320 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e  ULL if sufficien
1c330 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76  t memory is unav
1c340 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20  ailable..** ^If 
1c350 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  M is the size of
1c360 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1c370 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28  ation, then min(
1c380 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66  N,M) bytes.** of
1c390 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1c3a0 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64  ation are copied
1c3b0 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e   into the beginn
1c3c0 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65  ing of buffer re
1c3d0 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
1c3e0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61  ite3_realloc() a
1c3f0 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  nd the prior all
1c400 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64  ocation is freed
1c410 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1c420 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
1c430 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ns NULL, then th
1c440 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1c450 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65  on.** is not fre
1c460 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ed..**.** ^The m
1c470 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62  emory returned b
1c480 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
1c490 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
1c4a0 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61  ealloc().** is a
1c4b0 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f  lways aligned to
1c4c0 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62   at least an 8 b
1c4d0 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72  yte boundary, or
1c4e0 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20   to a.** 4 byte 
1c4f0 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20  boundary if the 
1c500 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41  [SQLITE_4_BYTE_A
1c510 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63  LIGNED_MALLOC] c
1c520 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
1c530 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ption is used..*
1c540 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76  *.** In SQLite v
1c550 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64  ersion 3.5.0 and
1c560 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70   3.5.1, it was p
1c570 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e  ossible to defin
1c580 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f  e.** the SQLITE_
1c590 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f  OMIT_MEMORY_ALLO
1c5a0 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75  CATION which wou
1c5b0 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69  ld cause the bui
1c5c0 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lt-in.** impleme
1c5d0 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65  ntation of these
1c5e0 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
1c5f0 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63  omitted.  That c
1c600 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
1c610 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64  no longer provid
1c620 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d  ed.  Only built-
1c630 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
1c640 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  tors can be used
1c650 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f  ..**.** Prior to
1c660 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
1c670 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64  3.7.10, the Wind
1c680 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ows OS interface
1c690 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a   layer called.**
1c6a0 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c   the system mall
1c6b0 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
1c6c0 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f  directly when co
1c6d0 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65  nverting.** file
1c6e0 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68  names between th
1c6f0 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  e UTF-8 encoding
1c700 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a   used by SQLite.
1c710 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20  ** and whatever 
1c720 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e  filename encodin
1c730 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65  g is used by the
1c740 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64   particular Wind
1c750 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74  ows.** installat
1c760 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c  ion.  Memory all
1c770 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77  ocation errors w
1c780 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75  ere detected, bu
1c790 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72  t.** they were r
1c7a0 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20  eported back as 
1c7b0 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
1c7c0 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
1c7d0 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68  IOERR] rather th
1c7e0 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  an [SQLITE_NOMEM
1c7f0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69  ]..**.** The poi
1c800 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74  nter arguments t
1c810 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
1c820 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1c830 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75  realloc()].** mu
1c840 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c  st be either NUL
1c850 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65  L or else pointe
1c860 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  rs obtained from
1c870 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f   a prior.** invo
1c880 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
1c890 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
1c8a0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1c8b0 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a  ()] that have.**
1c8c0 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65   not yet been re
1c8d0 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  leased..**.** Th
1c8e0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
1c8f0 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77  st not read or w
1c900 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66  rite any part of
1c910 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d  .** a block of m
1c920 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68  emory after it h
1c930 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  as been released
1c940 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
1c950 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73  e3_free()] or [s
1c960 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1c970 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  ]..*/.void *sqli
1c980 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b  te3_malloc(int);
1c990 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
1c9a0 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e  ealloc(void*, in
1c9b0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
1c9c0 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f  _free(void*);../
1c9d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
1c9e0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20  emory Allocator 
1c9f0 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a  Statistics.**.**
1ca00 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73   SQLite provides
1ca10 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72   these two inter
1ca20 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74  faces for report
1ca30 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75  ing on the statu
1ca40 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  s.** of the [sql
1ca50 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20  ite3_malloc()], 
1ca60 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1ca70 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  , and [sqlite3_r
1ca80 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75  ealloc()].** rou
1ca90 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72  tines, which for
1caa0 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d  m the built-in m
1cab0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1cac0 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a   subsystem..**.*
1cad0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
1cae0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72  memory_used()] r
1caf0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
1cb00 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
1cb10 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  es.** of memory 
1cb20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61  currently outsta
1cb30 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20  nding (malloced 
1cb40 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a  but not freed)..
1cb50 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
1cb60 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1cb70 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  r()] routine ret
1cb80 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  urns the maximum
1cb90 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71  .** value of [sq
1cba0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1cbb0 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68  d()] since the h
1cbc0 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
1cbd0 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74  * was last reset
1cbe0 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72  .  ^The values r
1cbf0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
1cc00 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1cc10 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1cc20 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1cc30 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61  ter()] include a
1cc40 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61  ny overhead.** a
1cc50 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69  dded by SQLite i
1cc60 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61  n its implementa
1cc70 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
1cc80 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62  _malloc()],.** b
1cc90 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20  ut not overhead 
1cca0 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79  added by the any
1ccb0 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74   underlying syst
1ccc0 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f  em library.** ro
1ccd0 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c  utines that [sql
1cce0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d  ite3_malloc()] m
1ccf0 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  ay call..**.** ^
1cd00 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d  The memory high-
1cd10 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65  water mark is re
1cd20 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65  set to the curre
1cd30 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b  nt value of.** [
1cd40 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1cd50 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e  sed()] if and on
1cd60 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ly if the parame
1cd70 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
1cd80 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1cd90 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20  ter()] is true. 
1cda0 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75   ^The value retu
1cdb0 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  rned.** by [sqli
1cdc0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1cdd0 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20  ater(1)] is the 
1cde0 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
1cdf0 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ** prior to the 
1ce00 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65  reset..*/.sqlite
1ce10 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
1ce20 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64  memory_used(void
1ce30 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
1ce40 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
1ce50 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65  highwater(int re
1ce60 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a  setFlag);../*.**
1ce70 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64   CAPI3REF: Pseud
1ce80 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20  o-Random Number 
1ce90 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20  Generator.**.** 
1cea0 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20  SQLite contains 
1ceb0 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70  a high-quality p
1cec0 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d  seudo-random num
1ced0 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50  ber generator (P
1cee0 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20  RNG) used to.** 
1cef0 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52  select random [R
1cf00 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77  OWID | ROWIDs] w
1cf10 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65  hen inserting ne
1cf20 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61  w records into a
1cf30 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61   table that.** a
1cf40 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20  lready uses the 
1cf50 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65  largest possible
1cf60 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50   [ROWID].  The P
1cf70 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64  RNG is also used
1cf80 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c   for.** the buil
1cf90 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e  d-in random() an
1cfa0 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53  d randomblob() S
1cfb0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  QL functions.  T
1cfc0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
1cfd0 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74  lows.** applicat
1cfe0 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74  ions to access t
1cff0 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72  he same PRNG for
1d000 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e   other purposes.
1d010 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  .**.** ^A call t
1d020 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73  o this routine s
1d030 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66  tores N bytes of
1d040 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
1d050 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 49   buffer P..** ^I
1d060 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
1d070 20 6f 6e 65 2c 20 74 68 65 6e 20 50 20 63 61 6e   one, then P can
1d080 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
1d090 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  er..**.** ^If th
1d0a0 69 73 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e  is routine has n
1d0b0 6f 74 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73  ot been previous
1d0c0 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20  ly called or if 
1d0d0 74 68 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20  the previous.** 
1d0e0 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20  call had N less 
1d0f0 74 68 61 6e 20 6f 6e 65 2c 20 74 68 65 6e 20 74  than one, then t
1d100 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65  he PRNG is seede
1d110 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65  d using randomne
1d120 73 73 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66  ss.** obtained f
1d130 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e  rom the xRandomn
1d140 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ess method of th
1d150 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
1d160 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
1d170 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 69  ** ^If the previ
1d180 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73  ous call to this
1d190 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20   routine had an 
1d1a0 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 74  N of 1 or more t
1d1b0 68 65 6e 0a 2a 2a 20 74 68 65 20 70 73 65 75 64  hen.** the pseud
1d1c0 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20  o-randomness is 
1d1d0 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74  generated.** int
1d1e0 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68  ernally and with
1d1f0 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20  out recourse to 
1d200 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
1d210 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a  ] xRandomness.**
1d220 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64   method..*/.void
1d230 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e   sqlite3_randomn
1d240 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20  ess(int N, void 
1d250 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *P);../*.** CAPI
1d260 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69  3REF: Compile-Ti
1d270 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  me Authorization
1d280 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
1d290 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
1d2a0 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68  egisters an auth
1d2b0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1d2c0 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
1d2d0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
1d2e0 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70  onnection], supp
1d2f0 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
1d300 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  t argument..** ^
1d310 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
1d320 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1d330 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
1d340 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
1d350 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
1d360 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1d370 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
1d380 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
1d390 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
1d3a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1d3b0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1d3c0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
1d3d0 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a    ^At various.**
1d3e0 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74   points during t
1d3f0 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70  he compilation p
1d400 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63  rocess, as logic
1d410 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65   is being create
1d420 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20  d.** to perform 
1d430 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c  various actions,
1d440 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1d450 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1d460 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66  ked to.** see if
1d470 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61   those actions a
1d480 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68  re allowed.  ^Th
1d490 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1d4a0 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20  lback should.** 
1d4b0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
1d4c0 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20  K] to allow the 
1d4d0 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f  action, [SQLITE_
1d4e0 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c  IGNORE] to disal
1d4f0 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69  low the.** speci
1d500 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61  fic action but a
1d510 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61  llow the SQL sta
1d520 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e  tement to contin
1d530 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ue to be.** comp
1d540 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  iled, or [SQLITE
1d550 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20  _DENY] to cause 
1d560 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73  the entire SQL s
1d570 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a  tatement to be.*
1d580 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20  * rejected with 
1d590 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74  an error.  ^If t
1d5a0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1d5b0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
1d5c0 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65  * any value othe
1d5d0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49  r than [SQLITE_I
1d5e0 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  GNORE], [SQLITE_
1d5f0 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OK], or [SQLITE_
1d600 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  DENY].** then th
1d610 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
1d620 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
1d630 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
1d640 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68   triggered.** th
1d650 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  e authorizer wil
1d660 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
1d670 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
1d680 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c  .** When the cal
1d690 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
1d6a0 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20  QLITE_OK], that 
1d6b0 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74  means the operat
1d6c0 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  ion.** requested
1d6d0 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74   is ok.  ^When t
1d6e0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1d6f0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59  rns [SQLITE_DENY
1d700 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ], the.** [sqlit
1d710 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1d720 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
1d730 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
1d740 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  ed the.** author
1d750 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
1d760 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
1d770 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20  sage explaining 
1d780 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69  that.** access i
1d790 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a  s denied. .**.**
1d7a0 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
1d7b0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
1d7c0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1d7d0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
1d7e0 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
1d7f0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
1d800 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1d810 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20  er() interface. 
1d820 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
1d830 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
1d840 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
1d850 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43  nteger [SQLITE_C
1d860 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
1d870 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
1d880 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75  s.** the particu
1d890 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  lar action to be
1d8a0 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68   authorized. ^Th
1d8b0 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
1d8c0 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
1d8d0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
1d8e0 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  ack are zero-ter
1d8f0 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
1d900 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64  that contain add
1d910 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69  itional.** detai
1d920 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
1d930 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
1d940 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ized..**.** ^If 
1d950 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
1d960 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  is [SQLITE_READ]
1d970 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  .** and the call
1d980 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1d990 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
1d9a0 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
1d9b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74  ed statement] st
1d9c0 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
1d9d0 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69  ructed to substi
1d9e0 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76  tute.** a NULL v
1d9f0 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
1da00 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
1da10 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
1da20 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69  e.** been read i
1da30 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61  f [SQLITE_OK] ha
1da40 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e  d been returned.
1da50 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47    The [SQLITE_IG
1da60 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20  NORE].** return 
1da70 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64  can be used to d
1da80 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64  eny an untrusted
1da90 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20   user access to 
1daa0 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f  individual.** co
1dab0 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65  lumns of a table
1dac0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  ..** ^If the act
1dad0 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
1dae0 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20  ITE_DELETE] and 
1daf0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1db00 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
1db10 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
1db20 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74   [DELETE] operat
1db30 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74  ion proceeds but
1db40 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74   the.** [truncat
1db50 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20  e optimization] 
1db60 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20  is disabled and 
1db70 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c  all rows are del
1db80 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  eted individuall
1db90 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  y..**.** An auth
1dba0 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
1dbb0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
1dbc0 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67  pare | preparing
1dbd0 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  ].** SQL stateme
1dbe0 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72  nts from an untr
1dbf0 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f  usted source, to
1dc00 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
1dc10 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
1dc20 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ** do not try to
1dc30 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65   access data the
1dc40 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  y are not allowe
1dc50 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61  d to see, or tha
1dc60 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
1dc70 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20   try to execute 
1dc80 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d  malicious statem
1dc90 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65  ents that damage
1dca0 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20   the database.  
1dcb0 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
1dcc0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
1dcd0 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20  ay allow a user 
1dce0 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61  to enter arbitra
1dcf0 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65  ry.** SQL querie
1dd00 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e  s for evaluation
1dd10 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20   by a database. 
1dd20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61   But the applica
1dd30 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  tion does.** not
1dd40 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74   want the user t
1dd50 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b  o be able to mak
1dd60 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e  e arbitrary chan
1dd70 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ges to the.** da
1dd80 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68  tabase.  An auth
1dd90 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65  orizer could the
1dda0 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63  n be put in plac
1ddb0 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75  e while the.** u
1ddc0 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20  ser-entered SQL 
1ddd0 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65  is being [sqlite
1dde0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
1ddf0 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69  ared] that.** di
1de00 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
1de10 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43  ng except [SELEC
1de20 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
1de30 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
1de40 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70  s that need to p
1de50 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20  rocess SQL from 
1de60 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
1de70 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20  s.** might also 
1de80 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e  consider lowerin
1de90 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74  g resource limit
1dea0 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  s using [sqlite3
1deb0 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64  _limit()].** and
1dec0 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61   limiting databa
1ded0 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68  se size using th
1dee0 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  e [max_page_coun
1def0 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69  t] [PRAGMA].** i
1df00 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73  n addition to us
1df10 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ing an authorize
1df20 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  r..**.** ^(Only 
1df30 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69  a single authori
1df40 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c  zer can be in pl
1df50 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73  ace on a databas
1df60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1df70 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68  at a time.  Each
1df80 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
1df90 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1dfa0 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
1dfb0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29   previous call.)
1dfc0 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20  ^  ^Disable the 
1dfd0 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e  authorizer by in
1dfe0 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20  stalling a NULL 
1dff0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  callback..** The
1e000 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64   authorizer is d
1e010 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
1e020 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  lt..**.** The au
1e030 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1e040 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
1e050 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
1e060 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
1e070 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1e080 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1e090 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1e0a0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65  allback..** Note
1e0b0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
1e0c0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
1e0d0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1e0e0 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
1e0f0 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
1e100 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
1e110 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
1e120 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
1e130 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
1e140 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f   ^When [sqlite3_
1e150 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73  prepare_v2()] is
1e160 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65   used to prepare
1e170 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68   a statement, th
1e180 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d  e.** statement m
1e190 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61  ight be re-prepa
1e1a0 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69  red during [sqli
1e1b0 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20  te3_step()] due 
1e1c0 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20  to a .** schema 
1e1d0 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20  change.  Hence, 
1e1e0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1e1f0 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68  should ensure th
1e200 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63  at the.** correc
1e210 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  t authorizer cal
1e220 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e  lback remains in
1e230 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68   place during th
1e240 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
1e250 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  )]..**.** ^Note 
1e260 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
1e270 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1e280 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72  invoked only dur
1e290 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1e2a0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
1e2b0 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
1e2c0 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
1e2d0 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
1e2e0 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
1e2f0 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
1e300 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
1e310 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61  unless.** as sta
1e320 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69  ted in the previ
1e330 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73  ous paragraph, s
1e340 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
1e350 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33  vokes.** sqlite3
1e360 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f  _prepare_v2() to
1e370 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61   reprepare a sta
1e380 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73  tement after a s
1e390 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f  chema change..*/
1e3a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74  .int sqlite3_set
1e3b0 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73  _authorizer(.  s
1e3c0 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28  qlite3*,.  int (
1e3d0 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e  *xAuth)(void*,in
1e3e0 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  t,const char*,co
1e3f0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1e400 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1e410 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65  *),.  void *pUse
1e420 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  rData.);../*.** 
1e430 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
1e440 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65  izer Return Code
1e450 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
1e460 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1e470 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
1e480 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1e490 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75  on] must.** retu
1e4a0 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  rn either [SQLIT
1e4b0 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  E_OK] or one of 
1e4c0 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61  these two consta
1e4d0 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20  nts in order.** 
1e4e0 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65  to signal SQLite
1e4f0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1e500 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65  the action is pe
1e510 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68  rmitted.  See th
1e520 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65  e.** [sqlite3_se
1e530 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
1e540 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65  uthorizer docume
1e550 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64  ntation] for add
1e560 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
1e570 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  mation..**.** No
1e580 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49  te that SQLITE_I
1e590 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73  GNORE is also us
1e5a0 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63  ed as a [conflic
1e5b0 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64  t resolution mod
1e5c0 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66  e].** returned f
1e5d0 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
1e5e0 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63  _vtab_on_conflic
1e5f0 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  t()] interface..
1e600 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e610 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20  E_DENY   1   /* 
1e620 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74  Abort the SQL st
1e630 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20  atement with an 
1e640 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
1e650 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32   SQLITE_IGNORE 2
1e660 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f     /* Don't allo
1e670 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f  w access, but do
1e680 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20  n't generate an 
1e690 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  error */../*.** 
1e6a0 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
1e6b0 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65  izer Action Code
1e6c0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
1e6d0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1e6e0 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  zer()] interface
1e6f0 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
1e700 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
1e710 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  * that is invoke
1e720 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63  d to authorize c
1e730 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65  ertain SQL state
1e740 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54  ment actions.  T
1e750 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
1e760 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
1e770 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
1e780 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73  eger code that s
1e790 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74  pecifies.** what
1e7a0 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67   action is being
1e7b0 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
1e7c0 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65  ese are the inte
1e7d0 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73  ger action codes
1e7e0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74   that.** the aut
1e7f0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1e800 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a   may be passed..
1e810 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69  **.** These acti
1e820 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73  on code values s
1e830 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64  ignify what kind
1e840 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73   of operation is
1e850 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72   to be.** author
1e860 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61  ized.  The 3rd a
1e870 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  nd 4th parameter
1e880 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  s to the authori
1e890 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  zation.** callba
1e8a0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  ck function will
1e8b0 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f   be parameters o
1e8c0 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67  r NULL depending
1e8d0 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65   on which of the
1e8e0 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75  se.** codes is u
1e8f0 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
1e900 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28  d parameter.  ^(
1e910 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  The 5th paramete
1e920 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68  r to the.** auth
1e930 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1e940 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
1e950 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61  he database ("ma
1e960 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20  in", "temp",.** 
1e970 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61  etc.) if applica
1e980 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68  ble.)^  ^The 6th
1e990 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1e9a0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1e9b0 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20  lback.** is the 
1e9c0 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65  name of the inne
1e9d0 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
1e9e0 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
1e9f0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
1ea00 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74  * the access att
1ea10 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20  empt or NULL if 
1ea20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65  this access atte
1ea30 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20  mpt is directly 
1ea40 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65  from.** top-leve
1ea50 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f  l SQL code..*/./
1ea60 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ea70 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ea80 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20  *********** 3rd 
1ea90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68  ************ 4th
1eaa0 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64   ***********/.#d
1eab0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1eac0 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ATE_INDEX       
1ead0 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20     1   /* Index 
1eae0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1eaf0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1eb00 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1eb10 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  TE_TABLE        
1eb20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    2   /* Table N
1eb30 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1eb40 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1eb50 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1eb60 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  E_TEMP_INDEX    
1eb70 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   3   /* Index Na
1eb80 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1eb90 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1eba0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1ebb0 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
1ebc0 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  4   /* Table Nam
1ebd0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1ebe0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1ebf0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1ec00 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35  TEMP_TRIGGER   5
1ec10 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1ec20 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1ec30 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1ec40 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1ec50 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20  EMP_VIEW      6 
1ec60 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1ec70 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1ec80 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1ec90 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52  SQLITE_CREATE_TR
1eca0 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20  IGGER        7  
1ecb0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1ecc0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1ecd0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1ece0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45  QLITE_CREATE_VIE
1ecf0 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20  W           8   
1ed00 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1ed10 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1ed20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1ed30 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20  LITE_DELETE     
1ed40 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f             9   /
1ed50 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1ed60 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1ed70 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1ed80 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20  ITE_DROP_INDEX  
1ed90 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a           10   /*
1eda0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1edb0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1edc0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1edd0 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20  TE_DROP_TABLE   
1ede0 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20          11   /* 
1edf0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1ee00 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1ee10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ee20 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45  E_DROP_TEMP_INDE
1ee30 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49  X      12   /* I
1ee40 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
1ee50 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1ee60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ee70 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45  _DROP_TEMP_TABLE
1ee80 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61        13   /* Ta
1ee90 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1eea0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1eeb0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1eec0 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45  DROP_TEMP_TRIGGE
1eed0 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69  R    14   /* Tri
1eee0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1eef0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1ef00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1ef10 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ROP_TEMP_VIEW   
1ef20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77      15   /* View
1ef30 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1ef40 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1ef50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1ef60 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  OP_TRIGGER      
1ef70 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67     16   /* Trigg
1ef80 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
1ef90 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1efa0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1efb0 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  P_VIEW          
1efc0 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e    17   /* View N
1efd0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
1efe0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1eff0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45  fine SQLITE_INSE
1f000 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RT              
1f010 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   18   /* Table N
1f020 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1f030 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1f040 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d  ine SQLITE_PRAGM
1f050 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
1f060 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e  19   /* Pragma N
1f070 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20  ame     1st arg 
1f080 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69  or NULL */.#defi
1f090 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20  ne SQLITE_READ  
1f0a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1f0b0 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
1f0c0 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
1f0d0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1f0e0 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20  e SQLITE_SELECT 
1f0f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
1f100 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
1f110 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1f120 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f130 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54   SQLITE_TRANSACT
1f140 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20  ION          22 
1f150 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
1f160 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1f170 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f180 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20  SQLITE_UPDATE   
1f190 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20              23  
1f1a0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1f1b0 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
1f1c0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f1d0 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20  QLITE_ATTACH    
1f1e0 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20             24   
1f1f0 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20  /* Filename     
1f200 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1f210 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f220 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20  LITE_DETACH     
1f230 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f            25   /
1f240 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
1f250 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1f260 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f270 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20  ITE_ALTER_TABLE 
1f280 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a           26   /*
1f290 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
1f2a0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f2b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f2c0 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20  TE_REINDEX      
1f2d0 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20          27   /* 
1f2e0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1f2f0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f300 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f310 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20  E_ANALYZE       
1f320 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54         28   /* T
1f330 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1f340 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1f350 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f360 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20  _CREATE_VTABLE  
1f370 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61        29   /* Ta
1f380 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
1f390 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
1f3a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f3b0 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20  DROP_VTABLE     
1f3c0 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62       30   /* Tab
1f3d0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
1f3e0 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
1f3f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
1f400 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  UNCTION         
1f410 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c      31   /* NULL
1f420 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63              Func
1f430 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23  tion Name   */.#
1f440 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41  define SQLITE_SA
1f450 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20  VEPOINT         
1f460 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61     32   /* Opera
1f470 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70  tion       Savep
1f480 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64  oint Name  */.#d
1f490 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50  efine SQLITE_COP
1f4a0 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Y               
1f4b0 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e     0   /* No lon
1f4c0 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66  ger used */.#def
1f4d0 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52  ine SQLITE_RECUR
1f4e0 53 49 56 45 20 20 20 20 20 20 20 20 20 20 20 20  SIVE            
1f4f0 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  33   /* NULL    
1f500 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
1f510 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a          */../*.*
1f520 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63  * CAPI3REF: Trac
1f530 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e  ing And Profilin
1f540 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
1f550 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1f560 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61   register callba
1f570 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ck functions tha
1f580 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f  t can be used fo
1f590 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64  r.** tracing and
1f5a0 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65   profiling the e
1f5b0 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20  xecution of SQL 
1f5c0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
1f5d0 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
1f5e0 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
1f5f0 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74  red by sqlite3_t
1f600 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  race() is invoke
1f610 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20  d at.** various 
1f620 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51  times when an SQ
1f630 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62  L statement is b
1f640 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c  eing run by [sql
1f650 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
1f660 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72   ^The sqlite3_tr
1f670 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  ace() callback i
1f680 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  s invoked with a
1f690 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67   UTF-8 rendering
1f6a0 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73   of the.** SQL s
1f6b0 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73  tatement text as
1f6c0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
1f6d0 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63  irst begins exec
1f6e0 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69  uting..** ^(Addi
1f6f0 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74  tional sqlite3_t
1f700 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73  race() callbacks
1f710 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
1f720 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65  as each triggere
1f730 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20  d subprogram is 
1f740 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61  entered.  The ca
1f750 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67  llbacks for trig
1f760 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  gers.** contain 
1f770 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d  a UTF-8 SQL comm
1f780 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66  ent that identif
1f790 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e  ies the trigger.
1f7a0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  )^.**.** The [SQ
1f7b0 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f  LITE_TRACE_SIZE_
1f7c0 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  LIMIT] compile-t
1f7d0 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  ime option can b
1f7e0 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a  e used to limit.
1f7f0 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  ** the length of
1f800 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65   [bound paramete
1f810 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20  r] expansion in 
1f820 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71  the output of sq
1f830 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a  lite3_trace()..*
1f840 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61  *.** ^The callba
1f850 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
1f860 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
1f870 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69  3_profile() is i
1f880 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63  nvoked.** as eac
1f890 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  h SQL statement 
1f8a0 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20  finishes.  ^The 
1f8b0 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
1f8c0 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65   contains.** the
1f8d0 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
1f8e0 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20  ent text and an 
1f8f0 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c  estimate of wall
1f900 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f  -clock time.** o
1f910 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20  f how long that 
1f920 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74  statement took t
1f930 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f  o run.  ^The pro
1f940 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  file callback.**
1f950 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74   time is in unit
1f960 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73  s of nanoseconds
1f970 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75  , however the cu
1f980 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61  rrent implementa
1f990 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20  tion.** is only 
1f9a0 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69  capable of milli
1f9b0 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f  second resolutio
1f9c0 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61  n so the six lea
1f9d0 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a  st significant.*
1f9e0 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20  * digits in the 
1f9f0 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67  time are meaning
1fa00 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65  less.  Future ve
1fa10 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1fa20 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64  .** might provid
1fa30 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75  e greater resolu
1fa40 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66  tion on the prof
1fa50 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20  iler callback.  
1fa60 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  The.** sqlite3_p
1fa70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f  rofile() functio
1fa80 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  n is considered 
1fa90 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64  experimental and
1faa0 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74   is.** subject t
1fab0 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75  o change in futu
1fac0 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1fad0 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  QLite..*/.void *
1fae0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71  sqlite3_trace(sq
1faf0 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54  lite3*, void(*xT
1fb00 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  race)(void*,cons
1fb10 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29  t char*), void*)
1fb20 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  ;.SQLITE_EXPERIM
1fb30 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69  ENTAL void *sqli
1fb40 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69  te3_profile(sqli
1fb50 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78  te3*,.   void(*x
1fb60 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63  Profile)(void*,c
1fb70 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74  onst char*,sqlit
1fb80 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64  e3_uint64), void
1fb90 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1fba0 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72  REF: Query Progr
1fbb0 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ess Callbacks.**
1fbc0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1fbd0 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
1fbe0 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72  r(D,N,X,P) inter
1fbf0 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20  face causes the 
1fc00 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
1fc10 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76  tion X to be inv
1fc20 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c  oked periodicall
1fc30 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75  y during long ru
1fc40 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a  nning calls to.*
1fc50 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
1fc60 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
1fc70 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  p()] and [sqlite
1fc80 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66  3_get_table()] f
1fc90 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  or.** database c
1fca0 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e  onnection D.  An
1fcb0 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72   example use for
1fcc0 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61   this.** interfa
1fcd0 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20  ce is to keep a 
1fce0 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69  GUI updated duri
1fcf0 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79  ng a large query
1fd00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72  ..**.** ^The par
1fd10 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73  ameter P is pass
1fd20 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
1fd30 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
1fd40 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c   to the .** call
1fd50 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e  back function X.
1fd60 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72    ^The parameter
1fd70 20 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f 78   N is the approx
1fd80 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20  imate number of 
1fd90 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63  .** [virtual mac
1fda0 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e  hine instruction
1fdb0 73 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c  s] that are eval
1fdc0 75 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75  uated between su
1fdd0 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f  ccessive.** invo
1fde0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63  cations of the c
1fdf0 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20  allback X.  ^If 
1fe00 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f  N is less than o
1fe10 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67  ne then the prog
1fe20 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20  ress.** handler 
1fe30 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a  is disabled..**.
1fe40 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  ** ^Only a singl
1fe50 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1fe60 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65  er may be define
1fe70 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65  d at one time pe
1fe80 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
1fe90 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74  onnection]; sett
1fea0 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65  ing a new progre
1feb0 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65  ss handler cance
1fec0 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e  ls the.** old on
1fed0 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72  e.  ^Setting par
1fee0 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c  ameter X to NULL
1fef0 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72   disables the pr
1ff00 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
1ff10 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73  ** ^The progress
1ff20 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f   handler is also
1ff30 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74   disabled by set
1ff40 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75  ting N to a valu
1ff50 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31  e less.** than 1
1ff60 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1ff70 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
1ff80 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
1ff90 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ro, the operatio
1ffa0 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70  n is.** interrup
1ffb0 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75  ted.  This featu
1ffc0 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  re can be used t
1ffd0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a  o implement a.**
1ffe0 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e   "Cancel" button
1fff0 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65   on a GUI progre
20000 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a  ss dialog box..*
20010 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73  *.** The progres
20020 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  s handler callba
20030 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  ck must not do a
20040 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
20050 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
20060 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
20070 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
20080 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
20090 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74  ndler..** Note t
200a0 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
200b0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
200c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
200d0 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
200e0 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
200f0 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
20100 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
20110 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
20120 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76  ragraph..**.*/.v
20130 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  oid sqlite3_prog
20140 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c  ress_handler(sql
20150 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28  ite3*, int, int(
20160 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
20170 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
20180 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65  EF: Opening A Ne
20190 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  w Database Conne
201a0 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ction.**.** ^The
201b0 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e  se routines open
201c0 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62   an SQLite datab
201d0 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63  ase file as spec
201e0 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a  ified by the .**
201f0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
20200 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d  nt. ^The filenam
20210 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e  e argument is in
20220 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46  terpreted as UTF
20230 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
20240 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
20250 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61  ite3_open_v2() a
20260 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  nd as UTF-16 in 
20270 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a  the native byte.
20280 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  ** order for sql
20290 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e  ite3_open16(). ^
202a0 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  (A [database con
202b0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
202c0 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65  is usually.** re
202d0 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c  turned in *ppDb,
202e0 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f   even if an erro
202f0 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f  r occurs.  The o
20300 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73  nly exception is
20310 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69   that.** if SQLi
20320 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
20330 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
20340 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c  to hold the [sql
20350 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a  ite3] object,.**
20360 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20   a NULL will be 
20370 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70  written into *pp
20380 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  Db instead of a 
20390 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
203a0 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65  sqlite3].** obje
203b0 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64  ct.)^ ^(If the d
203c0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
203d0 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65  d (and/or create
203e0 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c  d) successfully,
203f0 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45   then.** [SQLITE
20400 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64  _OK] is returned
20410 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20  .  Otherwise an 
20420 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
20430 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65  returned.)^ ^The
20440 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
20450 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  msg()] or [sqlit
20460 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72  e3_errmsg16()] r
20470 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75  outines can be u
20480 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a  sed to obtain.**
20490 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67   an English lang
204a0 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e  uage description
204b0 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f   of the error fo
204c0 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72  llowing a failur
204d0 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  e of any.** of t
204e0 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  he sqlite3_open(
204f0 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  ) routines..**.*
20500 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65  * ^The default e
20510 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20  ncoding for the 
20520 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
20530 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c   UTF-8 if.** sql
20540 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
20550 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
20560 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a   is called and.*
20570 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  * UTF-16 in the 
20580 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
20590 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  r if sqlite3_ope
205a0 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a  n16() is used..*
205b0 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20  *.** Whether or 
205c0 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  not an error occ
205d0 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f  urs when it is o
205e0 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73  pened, resources
205f0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
20600 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
20610 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
20620 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72  ndle should be r
20630 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61  eleased by.** pa
20640 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
20650 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68  ite3_close()] wh
20660 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67  en it is no long
20670 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  er required..**.
20680 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
20690 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61  pen_v2() interfa
206a0 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  ce works like sq
206b0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20  lite3_open().** 
206c0 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
206d0 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74  ccepts two addit
206e0 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73  ional parameters
206f0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
20700 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20  control.** over 
20710 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
20720 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28   connection.  ^(
20730 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  The flags parame
20740 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ter to.** sqlite
20750 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20  3_open_v2() can 
20760 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74  take one of.** t
20770 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
20780 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f  ee values, optio
20790 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
207a0 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
207b0 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
207c0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
207d0 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  FULLMUTEX], [SQL
207e0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
207f0 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ACHE],.** [SQLIT
20800 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
20810 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51  CHE], and/or [SQ
20820 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
20830 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64  lags:)^.**.** <d
20840 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  l>.** ^(<dt>[SQL
20850 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
20860 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  Y]</dt>.** <dd>T
20870 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
20880 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e  pened in read-on
20890 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ly mode.  If the
208a0 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
208b0 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78  ot.** already ex
208c0 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
208d0 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
208e0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
208f0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
20900 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RITE]</dt>.** <d
20910 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
20920 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
20930 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
20940 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72   if possible, or
20950 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79   reading.** only
20960 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
20970 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20  write protected 
20980 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  by the operating
20990 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74   system.  In eit
209a0 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20  her.** case the 
209b0 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c  database must al
209c0 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68  ready exist, oth
209d0 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20  erwise an error 
209e0 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
209f0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
20a00 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
20a10 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
20a20 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f  E_OPEN_CREATE]</
20a30 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
20a40 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
20a50 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
20a60 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69  d writing, and i
20a70 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20  s created if.** 
20a80 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65  it does not alre
20a90 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20  ady exist. This 
20aa0 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  is the behavior 
20ab0 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75  that is always u
20ac0 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  sed for.** sqlit
20ad0 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
20ae0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c  lite3_open16().<
20af0 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
20b00 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64  **.** If the 3rd
20b10 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
20b20 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
20b30 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
20b40 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  e.** combination
20b50 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70  s shown above op
20b60 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
20b70 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20  d with other.** 
20b80 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
20b90 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f  DONLY | SQLITE_O
20ba0 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74  PEN_* bits].** t
20bb0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
20bc0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
20bd0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51  *.** ^If the [SQ
20be0 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
20bf0 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20  X] flag is set, 
20c00 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
20c10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
20c20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c  opens in the mul
20c30 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
20c40 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f  ding mode] as lo
20c50 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65  ng as the single
20c60 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20  -thread.** mode 
20c70 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74  has not been set
20c80 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
20c90 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20   or start-time. 
20ca0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c   ^If the.** [SQL
20cb0 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
20cc0 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20  EX] flag is set 
20cd0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
20ce0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
20cf0 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72  ns.** in the ser
20d00 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
20d10 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20  ng mode] unless 
20d20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61  single-thread wa
20d30 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  s.** previously 
20d40 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70  selected at comp
20d50 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
20d60 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20  t-time..** ^The 
20d70 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
20d80 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63  REDCACHE] flag c
20d90 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
20da0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
20db0 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20   be.** eligible 
20dc0 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63  to use [shared c
20dd0 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61  ache mode], rega
20de0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
20df0 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a  r or not shared.
20e00 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62  ** cache is enab
20e10 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  led using [sqlit
20e20 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
20e30 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65  _cache()].  ^The
20e40 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
20e50 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66  _PRIVATECACHE] f
20e60 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
20e70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20e80 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72  on to not.** par
20e90 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61  ticipate in [sha
20ea0 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20  red cache mode] 
20eb0 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e  even if it is en
20ec0 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
20ed0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
20ee0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
20ef0 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e  en_v2() is the n
20f00 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ame of the.** [s
20f10 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
20f20 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
20f30 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
20f40 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
20f50 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64  hat.** the new d
20f60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20f70 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20  on should use.  
20f80 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70  ^If the fourth p
20f90 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61  arameter is.** a
20fa0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
20fb0 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  en the default [
20fc0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
20fd0 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ect is used..**.
20fe0 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
20ff0 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a  ame is ":memory:
21000 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  ", then a privat
21010 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d  e, temporary in-
21020 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a  memory database.
21030 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f  ** is created fo
21040 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  r the connection
21050 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f  .  ^This in-memo
21060 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  ry database will
21070 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20   vanish when.** 
21080 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
21090 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
210a0 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  d.  Future versi
210b0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
210c0 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20  ght.** make use 
210d0 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70  of additional sp
210e0 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20  ecial filenames 
210f0 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20  that begin with 
21100 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65  the ":" characte
21110 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f  r..** It is reco
21120 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65  mmended that whe
21130 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
21140 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64  ename actually d
21150 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a  oes begin with.*
21160 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65  * a ":" characte
21170 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65  r you should pre
21180 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  fix the filename
21190 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65   with a pathname
211a0 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22   such as.** "./"
211b0 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75   to avoid ambigu
211c0 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ity..**.** ^If t
211d0 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61  he filename is a
211e0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
211f0 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
21200 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d  temporary.** on-
21210 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69  disk database wi
21220 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20  ll be created.  
21230 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61  ^This private da
21240 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a  tabase will be.*
21250 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
21260 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20  deleted as soon 
21270 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  as the database 
21280 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
21290 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52  osed..**.** [[UR
212a0 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73  I filenames in s
212b0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20  qlite3_open()]] 
212c0 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65  <h3>URI Filename
212d0 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66  s</h3>.**.** ^If
212e0 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20   [URI filename] 
212f0 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
21300 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74  s enabled, and t
21310 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
21320 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77  ment.** begins w
21330 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65  ith "file:", the
21340 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  n the filename i
21350 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
21360 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20   a URI. ^URI.** 
21370 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72  filename interpr
21380 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  etation is enabl
21390 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  ed if the [SQLIT
213a0 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
213b0 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68   is.** set in th
213c0 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
213d0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  t to sqlite3_ope
213e0 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74  n_v2(), or if it
213f0 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61   has.** been ena
21400 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73  bled globally us
21410 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
21420 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69  CONFIG_URI] opti
21430 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  on with the.** [
21440 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
21450 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74  ] method or by t
21460 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  he [SQLITE_USE_U
21470 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  RI] compile-time
21480 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f   option..** As o
21490 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  f SQLite version
214a0 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65   3.7.7, URI file
214b0 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74  name interpretat
214c0 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66  ion is turned of
214d0 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c  f.** by default,
214e0 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65   but future rele
214f0 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ases of SQLite m
21500 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20  ight enable URI 
21510 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65  filename.** inte
21520 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65  rpretation by de
21530 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52  fault.  See "[UR
21540 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f  I filenames]" fo
21550 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
21560 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
21570 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  ** URI filenames
21580 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f   are parsed acco
21590 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38  rding to RFC 398
215a0 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63  6. ^If the URI c
215b0 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75  ontains an.** au
215c0 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74  thority, then it
215d0 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
215e0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
215f0 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a  or the string .*
21600 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e  * "localhost". ^
21610 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  If the authority
21620 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79   is not an empty
21630 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61   string or "loca
21640 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65  lhost", an .** e
21650 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
21660 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20   to the caller. 
21670 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f  ^The fragment co
21680 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
21690 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74  , if .** present
216a0 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  , is ignored..**
216b0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
216c0 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e   the path compon
216d0 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61  ent of the URI a
216e0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
216f0 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77  e disk file.** w
21700 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68  hich contains th
21710 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20  e database. ^If 
21720 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20  the path begins 
21730 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61  with a '/' chara
21740 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69  cter, .** then i
21750 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
21760 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   as an absolute 
21770 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61  path. ^If the pa
21780 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69  th does not begi
21790 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27  n .** with a '/'
217a0 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74   (meaning that t
217b0 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63  he authority sec
217c0 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20  tion is omitted 
217d0 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a  from the URI).**
217e0 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69   then the path i
217f0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
21800 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68   a relative path
21810 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77  . .** ^On window
21820 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d  s, the first com
21830 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73  ponent of an abs
21840 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69  olute path .** i
21850 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66  s a drive specif
21860 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43  ication (e.g. "C
21870 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72  :")..**.** [[cor
21880 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61  e URI query para
21890 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20  meters]].** The 
218a0 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
218b0 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e  of a URI may con
218c0 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20  tain parameters 
218d0 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72  that are interpr
218e0 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62  eted.** either b
218f0 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c  y SQLite itself,
21900 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20   or by a [VFS | 
21910 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65  custom VFS imple
21920 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53  mentation]..** S
21930 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73  QLite interprets
21940 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   the following t
21950 68 72 65 65 20 71 75 65 72 79 20 70 61 72 61 6d  hree query param
21960 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  eters:.**.** <ul
21970 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76  >.**   <li> <b>v
21980 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66  fs</b>: ^The "vf
21990 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  s" parameter may
219a0 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63   be used to spec
219b0 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a  ify the name of.
219c0 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a  **     a VFS obj
219d0 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65  ect that provide
219e0 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
219f0 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
21a00 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20   that should.** 
21a10 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61      be used to a
21a20 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
21a30 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e  se file on disk.
21a40 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e   ^If this option
21a50 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20   is set to.**   
21a60 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e    an empty strin
21a70 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  g the default VF
21a80 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  S object is used
21a90 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  . ^Specifying an
21aa0 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20   unknown.**     
21ab0 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e  VFS is an error.
21ac0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
21ad0 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
21ae0 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f  nd the vfs optio
21af0 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73  n is.**     pres
21b00 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46  ent, then the VF
21b10 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  S specified by t
21b20 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  he option takes 
21b30 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a  precedence over.
21b40 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65  **     the value
21b50 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
21b60 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
21b70 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
21b80 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
21b90 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20  i> <b>mode</b>: 
21ba0 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d  ^(The mode param
21bb0 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20  eter may be set 
21bc0 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20  to either "ro", 
21bd0 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77  "rw",.**     "rw
21be0 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e  c", or "memory".
21bf0 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73   Attempting to s
21c00 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68  et it to any oth
21c10 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20  er value is.**  
21c20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a     an error)^. .
21c30 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20  **     ^If "ro" 
21c40 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68  is specified, th
21c50 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
21c60 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
21c70 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20  ad-only .**     
21c80 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20  access, just as 
21c90 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
21ca0 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c  PEN_READONLY] fl
21cb0 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20  ag had been set 
21cc0 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74  in the .**     t
21cd0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
21ce0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
21cf0 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65  (). ^If the mode
21d00 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
21d10 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20  o .**     "rw", 
21d20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
21d30 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
21d40 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20  read-write (but 
21d50 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20  not create) .** 
21d60 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69      access, as i
21d70 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  f SQLITE_OPEN_RE
21d80 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74  ADWRITE (but not
21d90 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
21da0 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20  ATE) had .**    
21db0 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75   been set. ^Valu
21dc0 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76  e "rwc" is equiv
21dd0 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
21de0 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51   both .**     SQ
21df0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
21e00 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f  ITE and SQLITE_O
21e10 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66  PEN_CREATE.  ^If
21e20 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
21e30 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74   is.**     set t
21e40 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20  o "memory" then 
21e50 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72  a pure [in-memor
21e60 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74  y database] that
21e70 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20   never reads.** 
21e80 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72      or writes fr
21e90 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e  om disk is used.
21ea0 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72   ^It is an error
21eb0 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61   to specify a va
21ec0 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74  lue for.**     t
21ed0 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65  he mode paramete
21ee0 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72  r that is less r
21ef0 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20  estrictive than 
21f00 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62  that specified b
21f10 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61  y.**     the fla
21f20 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65  gs passed in the
21f30 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
21f40 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
21f50 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
21f60 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e  li> <b>cache</b>
21f70 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72  : ^The cache par
21f80 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
21f90 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61  t to either "sha
21fa0 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22  red" or.**     "
21fb0 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69  private". ^Setti
21fc0 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64  ng it to "shared
21fd0 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
21fe0 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a  to setting the.*
21ff0 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
22000 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69  N_SHAREDCACHE bi
22010 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61  t in the flags a
22020 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74  rgument passed t
22030 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33  o.**     sqlite3
22040 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74  _open_v2(). ^Set
22050 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70  ting the cache p
22060 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69  arameter to "pri
22070 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20  vate" is .**    
22080 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
22090 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54  etting the SQLIT
220a0 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
220b0 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20  CHE bit..**     
220c0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
220d0 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
220e0 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61  d the "cache" pa
220f0 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65  rameter is prese
22100 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55  nt in.**     a U
22110 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73  RI filename, its
22120 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73   value overrides
22130 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65   any behavior re
22140 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69  quested by setti
22150 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  ng.**     SQLITE
22160 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
22170 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45  HE or SQLITE_OPE
22180 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c  N_SHAREDCACHE fl
22190 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20  ag..**.**  <li> 
221a0 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68  <b>psow</b>: ^Th
221b0 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72  e psow parameter
221c0 20 6d 61 79 20 62 65 20 22 74 72 75 65 22 20 28   may be "true" (
221d0 6f 72 20 22 6f 6e 22 20 6f 72 20 22 79 65 73 22  or "on" or "yes"
221e0 20 6f 72 0a 2a 2a 20 20 20 20 20 22 31 22 29 20   or.**     "1") 
221f0 6f 72 20 22 66 61 6c 73 65 22 20 28 6f 72 20 22  or "false" (or "
22200 6f 66 66 22 20 6f 72 20 22 6e 6f 22 20 6f 72 20  off" or "no" or 
22210 22 30 22 29 20 74 6f 20 69 6e 64 69 63 61 74 65  "0") to indicate
22220 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20   that the.**    
22230 20 5b 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72   [powersafe over
22240 77 72 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20  write] property 
22250 64 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74  does or does not
22260 20 61 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a   apply to the.**
22270 20 20 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64       storage med
22280 69 61 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20  ia on which the 
22290 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 72 65  database file re
222a0 73 69 64 65 73 2e 20 20 5e 54 68 65 20 70 73 6f  sides.  ^The pso
222b0 77 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70  w query.**     p
222c0 61 72 61 6d 65 74 65 72 20 6f 6e 6c 79 20 77 6f  arameter only wo
222d0 72 6b 73 20 66 6f 72 20 74 68 65 20 62 75 69 6c  rks for the buil
222e0 74 2d 69 6e 20 75 6e 69 78 20 61 6e 64 20 57 69  t-in unix and Wi
222f0 6e 64 6f 77 73 20 56 46 53 65 73 2e 0a 2a 2a 0a  ndows VFSes..**.
22300 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f  **  <li> <b>nolo
22310 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c  ck</b>: ^The nol
22320 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73  ock parameter is
22330 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79   a boolean query
22340 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20   parameter.**   
22350 20 20 77 68 69 63 68 20 69 66 20 73 65 74 20 64    which if set d
22360 69 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63  isables file loc
22370 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b  king in rollback
22380 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20   journal modes. 
22390 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20   This.**     is 
223a0 75 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73  useful for acces
223b0 73 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20  sing a database 
223c0 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20  on a filesystem 
223d0 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  that does not.**
223e0 20 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63       support loc
223f0 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20  king.  Caution: 
22400 20 44 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   Database corrup
22410 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c  tion might resul
22420 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20  t if two.**     
22430 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65  or more processe
22440 73 20 77 72 69 74 65 20 74 6f 20 74 68 65 20 73  s write to the s
22450 61 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  ame database and
22460 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73   any one of thos
22470 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73  e.**     process
22480 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31  es uses nolock=1
22490 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
224a0 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20  >immutable</b>: 
224b0 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70  ^The immutable p
224c0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f  arameter is a bo
224d0 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20  olean query.**  
224e0 20 20 20 70 61 72 61 6d 65 74 65 72 20 74 68 61     parameter tha
224f0 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74  t indicates that
22500 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
22510 6c 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a  le is stored on.
22520 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79  **     read-only
22530 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69   media.  ^When i
22540 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c  mmutable is set,
22550 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
22560 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20  that the.**     
22570 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 63 61  database file ca
22580 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c  nnot be changed,
22590 20 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65   even by a proce
225a0 73 73 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a  ss with higher.*
225b0 2a 20 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c  *     privilege,
225c0 20 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61   and so the data
225d0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72  base is opened r
225e0 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c  ead-only and all
225f0 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20   locking.**     
22600 61 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65 63  and change detec
22610 74 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64  tion is disabled
22620 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74  .  Caution: Sett
22630 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c  ing the immutabl
22640 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74  e.**     propert
22650 79 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  y on a database 
22660 66 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69  file that does i
22670 6e 20 66 61 63 74 20 63 68 61 6e 67 65 20 63 61  n fact change ca
22680 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20  n result.**     
22690 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65  in incorrect que
226a0 72 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f  ry results and/o
226b0 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  r [SQLITE_CORRUP
226c0 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20  T] errors..**   
226d0 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c    See also: [SQL
226e0 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41  ITE_IOCAP_IMMUTA
226f0 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a  BLE]..**       .
22700 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
22710 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e  Specifying an un
22720 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20  known parameter 
22730 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d  in the query com
22740 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
22750 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72  is not an.** err
22760 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  or.  Future vers
22770 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
22780 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20  ight understand 
22790 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79  additional query
227a0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
227b0 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72   See "[query par
227c0 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65  ameters with spe
227d0 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20  cial meaning to 
227e0 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20  SQLite]" for.** 
227f0 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
22800 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  mation..**.** [[
22810 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
22820 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20  mples]] <h3>URI 
22830 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
22840 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61  s</h3>.**.** <ta
22850 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61  ble border="1" a
22860 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c  lign=center cell
22870 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74  padding=5>.** <t
22880 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e  r><th> URI filen
22890 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74  ames <th> Result
228a0 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  s.** <tr><td> fi
228b0 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  le:data.db <td> 
228c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
228d0 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61  n the file "data
228e0 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72  .db" in the curr
228f0 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ent directory..*
22900 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
22910 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
22920 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20  db<br>.**       
22930 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f     file:///home/
22940 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
22950 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  > .**          f
22960 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f  ile://localhost/
22970 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
22980 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20  b <br> <td> .** 
22990 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
229a0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
229b0 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  "/home/fred/data
229c0 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  .db"..** <tr><td
229d0 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61  > file://darksta
229e0 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  r/home/fred/data
229f0 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  .db <td> .**    
22a00 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20        An error. 
22a10 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f  "darkstar" is no
22a20 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61  t a recognized a
22a30 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72  uthority..** <tr
22a40 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74  ><td style="whit
22a50 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e  e-space:nowrap">
22a60 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
22a70 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e  le:///C:/Documen
22a80 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69  ts%20and%20Setti
22a90 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70  ngs/fred/Desktop
22aa0 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20  /data.db.**     
22ab0 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c  <td> Windows onl
22ac0 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65  y: Open the file
22ad0 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72   "data.db" on fr
22ae0 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20  ed's desktop on 
22af0 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  drive.**        
22b00 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20    C:. Note that 
22b10 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67  the %20 escaping
22b20 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65   in this example
22b30 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79   is not strictly
22b40 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65   .**          ne
22b50 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20  cessary - space 
22b60 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62  characters can b
22b70 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79  e used literally
22b80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
22b90 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a  URI filenames..*
22ba0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
22bb0 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26  data.db?mode=ro&
22bc0 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74  cache=private <t
22bd0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
22be0 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e  Open file "data.
22bf0 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
22c00 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72  nt directory for
22c10 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73   read-only acces
22c20 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52  s..**          R
22c30 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
22c40 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
22c50 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73  ed-cache mode is
22c60 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20   enabled by.**  
22c70 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c          default,
22c80 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63   use a private c
22c90 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ache..** <tr><td
22ca0 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
22cb0 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e  d/data.db?vfs=un
22cc0 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a  ix-dotfile <td>.
22cd0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
22ce0 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65   file "/home/fre
22cf0 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20  d/data.db". Use 
22d00 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20  the special VFS 
22d10 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a  "unix-dotfile".*
22d20 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20  *          that 
22d30 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69  uses dot-files i
22d40 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78  n place of posix
22d50 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e   advisory lockin
22d60 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  g..** <tr><td> f
22d70 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
22d80 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a  =readonly <td> .
22d90 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65  **          An e
22da0 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22  rror. "readonly"
22db0 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20   is not a valid 
22dc0 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22  option for the "
22dd0 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e  mode" parameter.
22de0 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a  .** </table>.**.
22df0 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69  ** ^URI hexadeci
22e00 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
22e10 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73  nces (%HH) are s
22e20 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20  upported within 
22e30 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20  the path and.** 
22e40 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
22e50 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78   of a URI. A hex
22e60 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
22e70 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74  sequence consist
22e80 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e  s of a.** percen
22e90 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66  t sign - "%" - f
22ea0 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74  ollowed by exact
22eb0 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d  ly two hexadecim
22ec0 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70  al digits .** sp
22ed0 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65  ecifying an octe
22ee0 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65  t value. ^Before
22ef0 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65   the path or que
22f00 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66  ry components of
22f10 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61   a.** URI filena
22f20 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  me are interpret
22f30 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63  ed, they are enc
22f40 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38  oded using UTF-8
22f50 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78   and all .** hex
22f60 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
22f70 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63  sequences replac
22f80 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62  ed by a single b
22f90 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  yte containing t
22fa0 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64  he.** correspond
22fb0 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68  ing octet. If th
22fc0 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72  is process gener
22fd0 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20  ates an invalid 
22fe0 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a  UTF-8 encoding,.
22ff0 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ** the results a
23000 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
23010 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
23020 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62  indows users:</b
23030 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20  >  The encoding 
23040 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c  used for the fil
23050 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
23060 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  * of sqlite3_ope
23070 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
23080 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62  open_v2() must b
23090 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61  e UTF-8, not wha
230a0 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67  tever.** codepag
230b0 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64  e is currently d
230c0 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d  efined.  Filenam
230d0 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e  es containing in
230e0 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63  ternational.** c
230f0 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62  haracters must b
23100 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55  e converted to U
23110 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61  TF-8 prior to pa
23120 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a  ssing them into.
23130 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
23140 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
23150 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62  n_v2()..**.** <b
23160 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
23170 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c   Runtime users:<
23180 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61  /b>  The tempora
23190 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73  ry directory mus
231a0 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f  t be set.** prio
231b0 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c  r to calling sql
231c0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
231d0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
231e0 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61  .  Otherwise, va
231f0 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65  rious.** feature
23200 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74  s that require t
23210 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72  he use of tempor
23220 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61  ary files may fa
23230 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  il..**.** See al
23240 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d  so: [sqlite3_tem
23250 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a  p_directory].*/.
23260 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
23270 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
23280 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
23290 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
232a0 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
232b0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
232c0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
232d0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
232e0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
232f0 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74  _open16(.  const
23300 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c   void *filename,
23310 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
23320 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29  ilename (UTF-16)
23330 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
23340 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
23350 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
23360 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
23370 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
23380 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
23390 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
233a0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
233b0 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
233c0 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
233d0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
233e0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
233f0 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
23400 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
23410 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
23420 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
23430 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
23440 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
23450 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
23460 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c  3REF: Obtain Val
23470 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61  ues For URI Para
23480 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65  meters.**.** The
23490 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72  se are utility r
234a0 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20  outines, useful 
234b0 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  to VFS implement
234c0 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65  ations, that che
234d0 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20  ck.** to see if 
234e0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
234f0 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63  was a URI that c
23500 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69  ontained a speci
23510 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61  fic query .** pa
23520 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20  rameter, and if 
23530 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76  so obtains the v
23540 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65  alue of that que
23550 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ry parameter..**
23560 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20  .** If F is the 
23570 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
23580 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  e pointer passed
23590 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28   into the xOpen(
235a0 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20  ) method of .** 
235b0 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  a VFS implementa
235c0 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c  tion when the fl
235d0 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
235e0 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65   xOpen() has one
235f0 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20   or .** more of 
23600 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
23610 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _URI] or [SQLITE
23620 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62  _OPEN_MAIN_DB] b
23630 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50  its set and.** P
23640 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
23650 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65  the query parame
23660 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  ter, then.** sql
23670 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
23680 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
23690 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
236a0 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20   P.** parameter 
236b0 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20  if it exists or 
236c0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
236d0 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70  f P does not app
236e0 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65  ear as a .** que
236f0 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ry parameter on 
23700 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75  F.  If P is a qu
23710 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66  ery parameter of
23720 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70   F.** has no exp
23730 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65  licit value, the
23740 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
23750 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
23760 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  urns.** a pointe
23770 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74  r to an empty st
23780 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
23790 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
237a0 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
237b0 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ne assumes that 
237c0 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a  P is a boolean.*
237d0 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  * parameter and 
237e0 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
237f0 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63   or false (0) ac
23800 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76  cording to the v
23810 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54  alue.** of P.  T
23820 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
23830 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
23840 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72  utine returns tr
23850 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a  ue (1) if the.**
23860 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20   value of query 
23870 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f  parameter P is o
23880 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72  ne of "yes", "tr
23890 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20  ue", or "on" in 
238a0 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69  any.** case or i
238b0 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
238c0 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65  ns with a non-ze
238d0 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20  ro number.  The 
238e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
238f0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
23900 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20  outines returns 
23910 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65  false (0) if the
23920 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65   value of.** que
23930 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
23940 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22  s one of "no", "
23950 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22  false", or "off"
23960 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a   in any case or.
23970 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  ** if the value 
23980 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75  begins with a nu
23990 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20  meric zero.  If 
239a0 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79  P is not a query
239b0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  .** parameter on
239c0 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c   F or if the val
239d0 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20  ue of P is does 
239e0 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66  not match any of
239f0 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74   the.** above, t
23a00 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
23a10 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
23a20 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a  eturns (B!=0)..*
23a30 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
23a40 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44  _uri_int64(F,P,D
23a50 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72  ) routine conver
23a60 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ts the value of 
23a70 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62  P into a.** 64-b
23a80 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
23a90 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68  r and returns th
23aa0 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44  at integer, or D
23ab0 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a   if P does not.*
23ac0 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65  * exist.  If the
23ad0 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73   value of P is s
23ae0 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
23af0 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20  han an integer, 
23b00 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20  then.** zero is 
23b10 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a  returned..** .**
23b20 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20   If F is a NULL 
23b30 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71  pointer, then sq
23b40 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
23b50 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
23b60 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c   NULL and.** sql
23b70 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
23b80 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
23b90 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20  B.  If F is not 
23ba0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  a NULL pointer a
23bb0 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64  nd.** is not a d
23bc0 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74  atabase file pat
23bd0 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68  hname pointer th
23be0 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64  at SQLite passed
23bf0 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a   into the xOpen.
23c00 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74  ** VFS method, t
23c10 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
23c20 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
23c30 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
23c40 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e  d probably.** un
23c50 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f  desirable..*/.co
23c60 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
23c70 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
23c80 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
23c90 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61  ename, const cha
23ca0 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20  r *zParam);.int 
23cb0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
23cc0 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ean(const char *
23cd0 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61  zFile, const cha
23ce0 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62  r *zParam, int b
23cf0 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65  Default);.sqlite
23d00 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
23d10 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20  uri_int64(const 
23d20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61  char*, const cha
23d30 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  r*, sqlite3_int6
23d40 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  4);.../*.** CAPI
23d50 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65  3REF: Error Code
23d60 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a  s And Messages.*
23d70 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
23d80 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65  3_errcode() inte
23d90 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
23da0 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c  e numeric [resul
23db0 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  t code] or.** [e
23dc0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
23dd0 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73  ode] for the mos
23de0 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20  t recent failed 
23df0 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
23e00 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ll.** associated
23e10 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
23e20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49  e connection]. I
23e30 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61  f a prior API ca
23e40 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74  ll failed.** but
23e50 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
23e60 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65   API call succee
23e70 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ded, the return 
23e80 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71  value from.** sq
23e90 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
23ea0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e  is undefined.  ^
23eb0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
23ec0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a  nded_errcode().*
23ed0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
23ee0 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74  he same except t
23ef0 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65  hat it always re
23f00 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65  turns the .** [e
23f10 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
23f20 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65  ode] even when e
23f30 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
23f40 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  odes are.** disa
23f50 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
23f60 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
23f70 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
23f80 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
23f90 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
23fa0 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
23fb0 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
23fc0 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
23fd0 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73  -8 or UTF-16 res
23fe0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28  pectively..** ^(
23ff0 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
24000 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
24010 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
24020 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a  ed internally..*
24030 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
24040 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  n does not need 
24050 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66  to worry about f
24060 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c  reeing the resul
24070 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  t..** However, t
24080 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20  he error string 
24090 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69  might be overwri
240a0 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tten or dealloca
240b0 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71  ted by.** subseq
240c0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74  uent calls to ot
240d0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
240e0 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29  face functions.)
240f0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
24100 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e  ite3_errstr() in
24110 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
24120 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  the English-lang
24130 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61  uage text.** tha
24140 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
24150 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61  [result code], a
24160 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65  s UTF-8..** ^(Me
24170 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
24180 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
24190 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
241a0 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61   internally.** a
241b0 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66  nd must not be f
241c0 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  reed by the appl
241d0 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a  ication)^..**.**
241e0 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c   When the serial
241f0 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
24200 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c  mode] is in use,
24210 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65   it might be the
24220 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20  .** case that a 
24230 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63  second error occ
24240 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74  urs on a separat
24250 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77  e thread in betw
24260 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20  een.** the time 
24270 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72  of the first err
24280 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20  or and the call 
24290 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
242a0 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61  ces..** When tha
242b0 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73  t happens, the s
242c0 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c  econd error will
242d0 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e   be reported sin
242e0 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65  ce these.** inte
242f0 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65  rfaces always re
24300 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65  port the most re
24310 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f  cent result.  To
24320 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20   avoid.** this, 
24330 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20  each thread can 
24340 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65  obtain exclusive
24350 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74   use of the [dat
24360 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24370 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69  ] D.** by invoki
24380 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
24390 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65  x_enter]([sqlite
243a0 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
243b0 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67  before beginning
243c0 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64  .** to use D and
243d0 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
243e0 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28  e3_mutex_leave](
243f0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
24400 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20  x](D)) after.** 
24410 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  all calls to the
24420 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74   interfaces list
24430 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70  ed here are comp
24440 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  leted..**.** If 
24450 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  an interface fai
24460 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d  ls with SQLITE_M
24470 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e  ISUSE, that mean
24480 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a  s the interface.
24490 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69  ** was invoked i
244a0 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68  ncorrectly by th
244b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
244c0 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68  In that case, th
244d0 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20  e.** error code 
244e0 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20  and message may 
244f0 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65  or may not be se
24500 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
24510 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  3_errcode(sqlite
24520 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69  3 *db);.int sqli
24530 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
24540 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
24550 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
24560 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71  qlite3_errmsg(sq
24570 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76  lite3*);.const v
24580 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  oid *sqlite3_err
24590 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b  msg16(sqlite3*);
245a0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
245b0 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29  ite3_errstr(int)
245c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
245d0 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  F: SQL Statement
245e0 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
245f0 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73  RDS: {prepared s
24600 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61  tatement} {prepa
24610 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a  red statements}.
24620 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
24630 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
24640 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69   represents a si
24650 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
24660 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  nt..** This obje
24670 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20  ct is variously 
24680 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70  known as a "prep
24690 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20  ared statement" 
246a0 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65  or a.** "compile
246b0 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22  d SQL statement"
246c0 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20   or simply as a 
246d0 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a  "statement"..**.
246e0 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61  ** The life of a
246f0 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63   statement objec
24700 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67  t goes something
24710 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
24720 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43  * <ol>.** <li> C
24730 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74  reate the object
24740 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
24750 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
24760 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20   a related.**   
24770 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20     function..** 
24780 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73  <li> Bind values
24790 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65   to [host parame
247a0 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20  ters] using the 
247b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
247c0 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61  .**      interfa
247d0 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e  ces..** <li> Run
247e0 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c   the SQL by call
247f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
24800 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  p()] one or more
24810 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
24820 52 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d  Reset the statem
24830 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
24840 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e  e3_reset()] then
24850 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20   go back.**     
24860 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20   to step 2.  Do 
24870 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  this zero or mor
24880 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
24890 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a   Destroy the obj
248a0 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
248b0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
248c0 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52  ** </ol>.**.** R
248d0 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74  efer to document
248e0 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
248f0 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  ual methods abov
24900 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  e for additional
24910 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
24920 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
24930 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ct sqlite3_stmt 
24940 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f  sqlite3_stmt;../
24950 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
24960 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a  un-time Limits.*
24970 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65  *.** ^(This inte
24980 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65  rface allows the
24990 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73   size of various
249a0 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
249b0 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20  e limited.** on 
249c0 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20  a connection by 
249d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73  connection basis
249e0 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
249f0 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
24a00 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
24a10 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d  ction] whose lim
24a20 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20  it is to be set 
24a30 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65  or queried.  The
24a40 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
24a50 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74  eter is one of t
24a60 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f  he [limit catego
24a70 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e  ries] that defin
24a80 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20  e a.** class of 
24a90 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
24aa0 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20   size limited.  
24ab0 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
24ac0 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65  ter is the.** ne
24ad0 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74  w limit for that
24ae0 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a   construct.)^.**
24af0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20  .** ^If the new 
24b00 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74  limit is a negat
24b10 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20  ive number, the 
24b20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67  limit is unchang
24b30 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63  ed..** ^(For eac
24b40 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79  h limit category
24b50 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69   SQLITE_LIMIT_<i
24b60 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20  >NAME</i> there 
24b70 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73  is a .** [limits
24b80 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f   | hard upper bo
24b90 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63  und].** set at c
24ba0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61  ompile-time by a
24bb0 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
24bc0 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20  macro called.** 
24bd0 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45  [limits | SQLITE
24be0 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  _MAX_<i>NAME</i>
24bf0 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d  ]..** (The "_LIM
24c00 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65  IT_" in the name
24c10 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22   is changed to "
24c20 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41  _MAX_".))^.** ^A
24c30 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65  ttempts to incre
24c40 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76  ase a limit abov
24c50 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72  e its hard upper
24c60 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69   bound are.** si
24c70 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
24c80 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70   to the hard upp
24c90 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20  er bound..**.** 
24ca0 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77  ^Regardless of w
24cb0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
24cc0 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e  e limit was chan
24cd0 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71  ged, the .** [sq
24ce0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69  lite3_limit()] i
24cf0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
24d00 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
24d10 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a   of the limit..*
24d20 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e  * ^Hence, to fin
24d30 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  d the current va
24d40 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77  lue of a limit w
24d50 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20  ithout changing 
24d60 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e  it,.** simply in
24d70 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66  voke this interf
24d80 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69  ace with the thi
24d90 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74  rd parameter set
24da0 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75   to -1..**.** Ru
24db0 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72  n-time limits ar
24dc0 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
24dd0 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f  se in applicatio
24de0 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a  ns that manage.*
24df0 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e  * both their own
24e00 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
24e10 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61  se and also data
24e20 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63  bases that are c
24e30 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20  ontrolled.** by 
24e40 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e  untrusted extern
24e50 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20  al sources.  An 
24e60 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74  example applicat
24e70 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a  ion might be a.*
24e80 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68  * web browser th
24e90 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64  at has its own d
24ea0 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f  atabases for sto
24eb0 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64  ring history and
24ec0 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74  .** separate dat
24ed0 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65  abases controlle
24ee0 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20  d by JavaScript 
24ef0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77  applications dow
24f00 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74  nloaded.** off t
24f10 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68  he Internet.  Th
24f20 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  e internal datab
24f30 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65  ases can be give
24f40 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20  n the.** large, 
24f50 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20  default limits. 
24f60 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67   Databases manag
24f70 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73  ed by external s
24f80 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65  ources can.** be
24f90 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c   given much smal
24fa0 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67  ler limits desig
24fb0 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61  ned to prevent a
24fc0 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69   denial of servi
24fd0 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44  ce.** attack.  D
24fe0 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20  evelopers might 
24ff0 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65  also want to use
25000 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   the [sqlite3_se
25010 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a  t_authorizer()].
25020 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  ** interface to 
25030 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20  further control 
25040 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20  untrusted SQL.  
25050 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
25060 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61  database.** crea
25070 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73  ted by an untrus
25080 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62  ted script can b
25090 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e  e contained usin
250a0 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61  g the.** [max_pa
250b0 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
250c0 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75  A]..**.** New ru
250d0 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74  n-time limit cat
250e0 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61  egories may be a
250f0 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
25100 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20  eleases..*/.int 
25110 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71  sqlite3_limit(sq
25120 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20  lite3*, int id, 
25130 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a  int newVal);../*
25140 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
25150 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74  n-Time Limit Cat
25160 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f  egories.** KEYWO
25170 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65  RDS: {limit cate
25180 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61  gory} {*limit ca
25190 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20  tegories}.**.** 
251a0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
251b0 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70  define various p
251c0 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74  erformance limit
251d0 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
251e0 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d   lowered at run-
251f0 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69  time using [sqli
25200 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a  te3_limit()]..**
25210 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66   The synopsis of
25220 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66   the meanings of
25230 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d   the various lim
25240 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c  its is shown bel
25250 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61  ow..** Additiona
25260 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  l information is
25270 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c   available at [l
25280 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69  imits | Limits i
25290 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a  n SQLite]..**.**
252a0 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
252b0 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d  E_LIMIT_LENGTH]]
252c0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
252d0 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  MIT_LENGTH</dt>.
252e0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
252f0 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73  um size of any s
25300 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72  tring or BLOB or
25310 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62   table row, in b
25320 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a  ytes.<dd>)^.**.*
25330 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
25340 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28  _SQL_LENGTH]] ^(
25350 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
25360 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  _SQL_LENGTH</dt>
25370 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
25380 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e  mum length of an
25390 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
253a0 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e  in bytes.</dd>)^
253b0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
253c0 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e  LIMIT_COLUMN]] ^
253d0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
253e0 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a  T_COLUMN</dt>.**
253f0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
25400 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
25410 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65  ns in a table de
25420 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74  finition or in t
25430 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74  he.** result set
25440 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f   of a [SELECT] o
25450 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  r the maximum nu
25460 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
25470 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f  in an index.** o
25480 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59  r in an ORDER BY
25490 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61   or GROUP BY cla
254a0 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  use.</dd>)^.**.*
254b0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
254c0 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28  _EXPR_DEPTH]] ^(
254d0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
254e0 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e  _EXPR_DEPTH</dt>
254f0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
25500 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65  mum depth of the
25510 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61   parse tree on a
25520 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f  ny expression.</
25530 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
25540 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
25550 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c  UND_SELECT]] ^(<
25560 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
25570 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c  COMPOUND_SELECT<
25580 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
25590 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
255a0 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d  f terms in a com
255b0 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61  pound SELECT sta
255c0 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a  tement.</dd>)^.*
255d0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
255e0 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28  MIT_VDBE_OP]] ^(
255f0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
25600 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a  _VDBE_OP</dt>.**
25610 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
25620 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72   number of instr
25630 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72  uctions in a vir
25640 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f  tual machine pro
25650 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20  gram.** used to 
25660 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c  implement an SQL
25670 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69   statement.  Thi
25680 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  s limit is not c
25690 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f  urrently.** enfo
256a0 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61  rced, though tha
256b0 74 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 64  t might be added
256c0 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
256d0 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51  release of.** SQ
256e0 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  Lite.</dd>)^.**.
256f0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
25700 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d  T_FUNCTION_ARG]]
25710 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
25720 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
25730 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
25740 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
25750 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20  of arguments on 
25760 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e  a function.</dd>
25770 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
25780 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
25790 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
257a0 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f  LIMIT_ATTACHED</
257b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
257c0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
257d0 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63   [ATTACH | attac
257e0 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29  hed databases].)
257f0 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ^</dd>.**.** [[S
25800 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
25810 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d  _PATTERN_LENGTH]
25820 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
25830 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
25840 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  TERN_LENGTH</dt>
25850 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
25860 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  mum length of th
25870 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65  e pattern argume
25880 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d  nt to the [LIKE]
25890 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70   or.** [GLOB] op
258a0 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a  erators.</dd>)^.
258b0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
258c0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
258d0 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e  MBER]].** ^(<dt>
258e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
258f0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74  IABLE_NUMBER</dt
25900 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
25910 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65  imum index numbe
25920 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65  r of any [parame
25930 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73  ter] in an SQL s
25940 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a  tatement.)^.**.*
25950 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
25960 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d  _TRIGGER_DEPTH]]
25970 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
25980 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
25990 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
259a0 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
259b0 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72  of recursion for
259c0 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29   triggers.</dd>)
259d0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
259e0 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48  _LIMIT_WORKER_TH
259f0 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51  READS]] ^(<dt>SQ
25a00 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45  LITE_LIMIT_WORKE
25a10 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a  R_THREADS</dt>.*
25a20 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
25a30 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69  m number of auxi
25a40 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72  liary worker thr
25a50 65 61 64 73 20 74 68 61 74 20 61 20 73 69 6e 67  eads that a sing
25a60 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  le.** [prepared 
25a70 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73  statement] may s
25a80 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  tart.</dd>)^.** 
25a90 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
25aa0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45   SQLITE_LIMIT_LE
25ab0 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
25ac0 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
25ad0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  e SQLITE_LIMIT_S
25ae0 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  QL_LENGTH       
25af0 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
25b00 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
25b10 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20  COLUMN          
25b20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
25b30 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
25b40 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20  _EXPR_DEPTH     
25b50 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65             3.#de
25b60 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
25b70 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
25b80 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64  T           4.#d
25b90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
25ba0 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20  IT_VDBE_OP      
25bb0 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
25bc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
25bd0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
25be0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
25bf0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
25c00 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20  IMIT_ATTACHED   
25c10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37                 7
25c20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
25c30 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
25c40 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  RN_LENGTH       
25c50 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
25c60 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
25c70 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20  NUMBER          
25c80 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
25c90 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
25ca0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
25cb0 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   10.#define SQLI
25cc0 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f  TE_LIMIT_WORKER_
25cd0 54 48 52 45 41 44 53 20 20 20 20 20 20 20 20 20  THREADS         
25ce0 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    11../*.** CAPI
25cf0 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20  3REF: Compiling 
25d00 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
25d10 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
25d20 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
25d30 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20  piler}.**.** To 
25d40 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71  execute an SQL q
25d50 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69  uery, it must fi
25d60 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  rst be compiled 
25d70 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65  into a byte-code
25d80 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e  .** program usin
25d90 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72  g one of these r
25da0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
25db0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
25dc0 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64  t, "db", is a [d
25dd0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
25de0 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  on] obtained fro
25df0 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63  m a.** prior suc
25e00 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
25e10 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
25e20 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
25e30 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  v2()] or.** [sql
25e40 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20  ite3_open16()]. 
25e50 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   The database co
25e60 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  nnection must no
25e70 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73  t have been clos
25e80 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ed..**.** The se
25e90 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22  cond argument, "
25ea0 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74  zSql", is the st
25eb0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
25ec0 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a  mpiled, encoded.
25ed0 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46  ** as either UTF
25ee0 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54  -8 or UTF-16.  T
25ef0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
25f00 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  re() and sqlite3
25f10 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a  _prepare_v2().**
25f20 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20   interfaces use 
25f30 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74  UTF-8, and sqlit
25f40 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61  e3_prepare16() a
25f50 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
25f60 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65  re16_v2().** use
25f70 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e   UTF-16..**.** ^
25f80 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
25f90 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68  ument is less th
25fa0 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53  an zero, then zS
25fb0 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f  ql is read up to
25fc0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65   the.** first ze
25fd0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e  ro terminator. ^
25fe0 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  If nByte is non-
25ff0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69  negative, then i
26000 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  t is the maximum
26010 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62  .** number of  b
26020 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a  ytes read from z
26030 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74  Sql.  ^When nByt
26040 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  e is non-negativ
26050 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73  e, the.** zSql s
26060 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69  tring ends at ei
26070 74 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27  ther the first '
26080 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30  \000' or '\u0000
26090 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a  ' character or.*
260a0 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62  * the nByte-th b
260b0 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63  yte, whichever c
260c0 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74  omes first. If t
260d0 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a  he caller knows.
260e0 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70  ** that the supp
260f0 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e  lied string is n
26100 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74  ul-terminated, t
26110 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73  hen there is a s
26120 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61  mall.** performa
26130 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f  nce advantage to
26140 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61   be gained by pa
26150 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70  ssing an nByte p
26160 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a  arameter that.**
26170 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65   is equal to the
26180 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
26190 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   in the input st
261a0 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e  ring <i>includin
261b0 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c  g</i>.** the nul
261c0 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65  -terminator byte
261d0 73 20 61 73 20 74 68 69 73 20 73 61 76 65 73 20  s as this saves 
261e0 53 51 4c 69 74 65 20 66 72 6f 6d 20 68 61 76 69  SQLite from havi
261f0 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20  ng to.** make a 
26200 63 6f 70 79 20 6f 66 20 74 68 65 20 69 6e 70 75  copy of the inpu
26210 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  t string..**.** 
26220 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f  ^If pzTail is no
26230 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54  t NULL then *pzT
26240 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ail is made to p
26250 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73  oint to the firs
26260 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74  t byte.** past t
26270 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69  he end of the fi
26280 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  rst SQL statemen
26290 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73  t in zSql.  Thes
262a0 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a  e routines only.
262b0 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66  ** compile the f
262c0 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69  irst statement i
262d0 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61  n zSql, so *pzTa
262e0 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  il is left point
262f0 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72  ing to.** what r
26300 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65  emains uncompile
26310 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d  d..**.** ^*ppStm
26320 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  t is left pointi
26330 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64  ng to a compiled
26340 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
26350 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62  ment] that can b
26360 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73  e.** executed us
26370 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
26380 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65  p()].  ^If there
26390 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70   is an error, *p
263a0 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20  pStmt is set.** 
263b0 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68  to NULL.  ^If th
263c0 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e  e input text con
263d0 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66  tains no SQL (if
263e0 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e   the input is an
263f0 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67   empty.** string
26400 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74   or a comment) t
26410 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73  hen *ppStmt is s
26420 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54  et to NULL..** T
26430 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65  he calling proce
26440 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69  dure is responsi
26450 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67  ble for deleting
26460 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a   the compiled.**
26470 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75   SQL statement u
26480 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
26490 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20  nalize()] after 
264a0 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
264b0 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74  with it..** ppSt
264c0 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55  mt may not be NU
264d0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75  LL..**.** ^On su
264e0 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74  ccess, the sqlit
264f0 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d  e3_prepare() fam
26500 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20  ily of routines 
26510 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
26520 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65  K];.** otherwise
26530 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
26540 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
26550 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
26560 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64  prepare_v2() and
26570 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
26580 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  16_v2() interfac
26590 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d  es are.** recomm
265a0 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65  ended for all ne
265b0 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20  w programs. The 
265c0 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66  two older interf
265d0 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65  aces are retaine
265e0 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72  d.** for backwar
265f0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
26600 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20  , but their use 
26610 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a  is discouraged..
26620 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  ** ^In the "v2" 
26630 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
26640 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26650 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65  nt.** that is re
26660 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c  turned (the [sql
26670 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
26680 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f  t) contains a co
26690 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69  py of the.** ori
266a0 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20  ginal SQL text. 
266b0 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20  This causes the 
266c0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
266d0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a   interface to.**
266e0 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e   behave differen
266f0 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79  tly in three way
26700 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
26710 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
26720 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
26730 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61   changes, instea
26740 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b  d of returning [
26750 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61  SQLITE_SCHEMA] a
26760 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75  s it.** always u
26770 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69  sed to do, [sqli
26780 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
26790 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
267a0 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c  ecompile the SQL
267b0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  .** statement an
267c0 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20  d try to run it 
267d0 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61  again. As many a
267e0 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43  s [SQLITE_MAX_SC
267f0 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72  HEMA_RETRY].** r
26800 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75  etries will occu
26810 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33  r before sqlite3
26820 5f 73 74 65 70 28 29 20 67 69 76 65 73 20 75 70  _step() gives up
26830 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20   and returns an 
26840 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  error..** </li>.
26850 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57  **.** <li>.** ^W
26860 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  hen an error occ
26870 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  urs, [sqlite3_st
26880 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ep()] will retur
26890 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74  n one of the det
268a0 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20  ailed.** [error 
268b0 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e  codes] or [exten
268c0 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d  ded error codes]
268d0 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62  .  ^The legacy b
268e0 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74  ehavior was that
268f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
26900 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20  p()] would only 
26910 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63  return a generic
26920 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
26930 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61  result code.** a
26940 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
26950 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f  on would have to
26960 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63   make a second c
26970 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
26980 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f  reset()].** in o
26990 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65  rder to find the
269a0 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73   underlying caus
269b0 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d  e of the problem
269c0 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20  . With the "v2" 
269d0 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72  prepare.** inter
269e0 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72  faces, the under
269f0 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72  lying reason for
26a00 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65   the error is re
26a10 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
26a20 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  ly..** </li>.**.
26a30 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
26a40 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75  he specific valu
26a50 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61  e bound to [para
26a60 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72  meter | host par
26a70 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a  ameter] in the .
26a80 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ** WHERE clause 
26a90 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20  might influence 
26aa0 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75  the choice of qu
26ab0 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73  ery plan for a s
26ac0 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65  tatement,.** the
26ad0 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  n the statement 
26ae0 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
26af0 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64  cally recompiled
26b00 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61  , as if there ha
26b10 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68  d been .** a sch
26b20 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74  ema change, on t
26b30 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74  he first  [sqlit
26b40 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20  e3_step()] call 
26b50 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68  following any ch
26b60 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ange.** to the [
26b70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
26b80 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66  t | bindings] of
26b90 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72   that [parameter
26ba0 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63  ]. .** ^The spec
26bb0 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48  ific value of WH
26bc0 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61  ERE-clause [para
26bd0 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66  meter] might inf
26be0 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63  luence the .** c
26bf0 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
26c00 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d  lan if the param
26c10 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74  eter is the left
26c20 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20  -hand side of a 
26c30 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c  [LIKE].** or [GL
26c40 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20  OB] operator or 
26c50 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
26c60 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20   is compared to 
26c70 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d  an indexed colum
26c80 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51  n.** and the [SQ
26c90 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54  LITE_ENABLE_STAT
26ca0 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  3] compile-time 
26cb0 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  option is enable
26cc0 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c  d..** </li>.** <
26cd0 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  /ol>.*/.int sqli
26ce0 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73  te3_prepare(.  s
26cf0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
26d00 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
26d10 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
26d20 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
26d30 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
26d40 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
26d50 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
26d60 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
26d70 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
26d80 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
26d90 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
26da0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
26db0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
26dc0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
26dd0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
26de0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
26df0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
26e00 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
26e10 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
26e20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
26e30 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
26e40 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
26e50 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
26e60 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
26e70 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
26e80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
26e90 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
26ea0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
26eb0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
26ec0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
26ed0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
26ee0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
26ef0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
26f00 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
26f10 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
26f20 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
26f30 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
26f40 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
26f50 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
26f60 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
26f70 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65  pare16(.  sqlite
26f80 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
26f90 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
26fa0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
26fb0 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
26fc0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
26fd0 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
26fe0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
26ff0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
27000 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
27010 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
27020 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
27030 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
27040 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
27050 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
27060 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
27070 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
27080 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
27090 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
270a0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
270b0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
270c0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
270d0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
270e0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
270f0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
27100 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
27110 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
27120 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
27130 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
27140 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
27150 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
27160 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
27170 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
27180 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
27190 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
271a0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
271b0 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
271c0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
271d0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
271e0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
271f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27200 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74   Retrieving Stat
27210 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20  ement SQL.**.** 
27220 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  ^This interface 
27230 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
27240 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20  etrieve a saved 
27250 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67  copy of the orig
27260 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74  inal.** SQL text
27270 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20   used to create 
27280 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
27290 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73  ement] if that s
272a0 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20  tatement was.** 
272b0 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65  compiled using e
272c0 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
272d0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
272e0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
272f0 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e  16_v2()]..*/.con
27300 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
27310 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  _sql(sqlite3_stm
27320 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
27330 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
27340 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
27350 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73  Statement Writes
27360 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a   The Database.**
27370 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
27380 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58  _stmt_readonly(X
27390 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
273a0 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
273b0 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e  ro) if.** and on
273c0 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61  ly if the [prepa
273d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58  red statement] X
273e0 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74   makes no direct
273f0 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74   changes to.** t
27400 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
27410 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  e database file.
27420 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
27430 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
27440 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
27450 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74  ons] or.** [virt
27460 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68  ual tables] migh
27470 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  t change the dat
27480 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79  abase indirectly
27490 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63   as a side effec
274a0 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  t.  .** ^(For ex
274b0 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70  ample, if an app
274c0 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73  lication defines
274d0 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61   a function "eva
274e0 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61  l()" that .** ca
274f0 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  lls [sqlite3_exe
27500 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66  c()], then the f
27510 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61  ollowing SQL sta
27520 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20  tement would.** 
27530 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
27540 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68  ase file through
27550 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a   side-effects:.*
27560 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
27570 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c  ><pre>.**    SEL
27580 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45  ECT eval('DELETE
27590 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20   FROM t1') FROM 
275a0 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  t2;.** </pre></b
275b0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
275c0 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65   But because the
275d0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
275e0 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ent does not cha
275f0 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
27600 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c   file.** directl
27610 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  y, sqlite3_stmt_
27620 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64  readonly() would
27630 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72   still return tr
27640 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61  ue.)^.**.** ^Tra
27650 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c  nsaction control
27660 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68   statements such
27670 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f   as [BEGIN], [CO
27680 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b  MMIT], [ROLLBACK
27690 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54  ],.** [SAVEPOINT
276a0 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d  ], and [RELEASE]
276b0 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73   cause sqlite3_s
276c0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
276d0 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a  o return true,.*
276e0 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74  * since the stat
276f0 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65  ements themselve
27700 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c  s do not actuall
27710 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  y modify the dat
27720 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74  abase but.** rat
27730 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c  her they control
27740 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77   the timing of w
27750 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d  hen other statem
27760 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20  ents modify the 
27770 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e  .** database.  ^
27780 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64  The [ATTACH] and
27790 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d   [DETACH] statem
277a0 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a  ents also cause.
277b0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  ** sqlite3_stmt_
277c0 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65  readonly() to re
277d0 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c  turn true since,
277e0 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61   while those sta
277f0 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67  tements.** chang
27800 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  e the configurat
27810 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73  ion of a databas
27820 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68  e connection, th
27830 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a  ey do not make .
27840 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ** changes to th
27850 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
27860 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20   database files 
27870 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20  on disk..*/.int 
27880 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
27890 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74  donly(sqlite3_st
278a0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
278b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
278c0 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70  ermine If A Prep
278d0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48  ared Statement H
278e0 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a  as Been Reset.**
278f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
27900 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e  _stmt_busy(S) in
27910 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
27920 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20  true (non-zero) 
27930 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  if the.** [prepa
27940 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
27950 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70 65   has been steppe
27960 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20  d at least once 
27970 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
27980 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20  e3_step(S)] but 
27990 68 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20 63  has not run to c
279a0 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f 72  ompletion and/or
279b0 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65 65   has not .** bee
279c0 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73  n reset using [s
279d0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
279e0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
279f0 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20  stmt_busy(S).** 
27a00 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
27a10 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 20  s false if S is 
27a20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
27a30 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a   If S is not a .
27a40 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
27a50 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69  and is not a poi
27a60 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20  nter to a valid 
27a70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
27a80 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20  ent].** object, 
27a90 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
27aa0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  r is undefined a
27ab0 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65  nd probably unde
27ac0 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54  sirable..**.** T
27ad0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
27ae0 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d  n be used in com
27af0 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65  bination [sqlite
27b00 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a  3_next_stmt()].*
27b10 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20  * to locate all 
27b20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27b30 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77  nts associated w
27b40 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20 0a  ith a database .
27b50 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  ** connection th
27b60 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f  at are in need o
27b70 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20  f being reset.  
27b80 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64  This can be used
27b90 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65  ,.** for example
27ba0 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20  , in diagnostic 
27bb0 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72  routines to sear
27bc0 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 20  ch for prepared 
27bd0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74  .** statements t
27be0 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20  hat are holding 
27bf0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70  a transaction op
27c00 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  en..*/.int sqlit
27c10 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c  e3_stmt_busy(sql
27c20 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
27c30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79  .** CAPI3REF: Dy
27c40 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20  namically Typed 
27c50 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20  Value Object.** 
27c60 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65  KEYWORDS: {prote
27c70 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
27c80 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64  ue} {unprotected
27c90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a   sqlite3_value}.
27ca0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
27cb0 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61  s the sqlite3_va
27cc0 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65  lue object to re
27cd0 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75  present all valu
27ce0 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  es.** that can b
27cf0 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61  e stored in a da
27d00 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51  tabase table. SQ
27d10 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
27d20 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20  c typing.** for 
27d30 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74  the values it st
27d40 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73  ores.  ^Values s
27d50 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33  tored in sqlite3
27d60 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a  _value objects.*
27d70 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72  * can be integer
27d80 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  s, floating poin
27d90 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67  t values, string
27da0 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c  s, BLOBs, or NUL
27db0 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69  L..**.** An sqli
27dc0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
27dd0 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22   may be either "
27de0 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75  protected" or "u
27df0 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20  nprotected"..** 
27e00 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20  Some interfaces 
27e10 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63  require a protec
27e20 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
27e30 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66  e.  Other interf
27e40 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63  aces.** will acc
27e50 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f  ept either a pro
27e60 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70  tected or an unp
27e70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
27e80 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79  _value..** Every
27e90 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
27ea0 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f  accepts sqlite3_
27eb0 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20  value arguments 
27ec0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65  specifies.** whe
27ed0 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72  ther or not it r
27ee0 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63  equires a protec
27ef0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
27f00 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72  e..**.** The ter
27f10 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61  ms "protected" a
27f20 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  nd "unprotected"
27f30 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65   refer to whethe
27f40 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75  r or not.** a mu
27f50 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e  tex is held.  An
27f60 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20   internal mutex 
27f70 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72  is held for a pr
27f80 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
27f90 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
27fa0 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20  but no mutex is 
27fb0 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72  held for an unpr
27fc0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
27fd0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e  e3_value object.
27fe0 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
27ff0 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69  ompiled to be si
28000 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ngle-threaded.**
28010 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54   (with [SQLITE_T
28020 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64  HREADSAFE=0] and
28030 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74   with [sqlite3_t
28040 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74  hreadsafe()] ret
28050 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20  urning 0).** or 
28060 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e  if SQLite is run
28070 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63   in one of reduc
28080 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a  ed mutex modes .
28090 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
280a0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20  G_SINGLETHREAD] 
280b0 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
280c0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a  G_MULTITHREAD].*
280d0 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  * then there is 
280e0 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  no distinction b
280f0 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
28100 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
28110 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
28120 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68  e objects and th
28130 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ey can be used i
28140 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20  nterchangeably. 
28150 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72   However,.** for
28160 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f   maximum code po
28170 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20  rtability it is 
28180 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
28190 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
281a0 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20   still make the 
281b0 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
281c0 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
281d0 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
281e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
281f0 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e  bjects even when
28200 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65   not strictly re
28210 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  quired..**.** ^T
28220 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
28230 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72   objects that ar
28240 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61  e passed as para
28250 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a  meters into the.
28260 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
28270 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f  n of [applicatio
28280 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
28290 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f  nctions] are pro
282a0 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  tected..** ^The 
282b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
282c0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
282d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
282e0 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
282f0 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  unprotected..** 
28300 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  Unprotected sqli
28310 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
28320 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  s may only be us
28330 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69  ed with.** [sqli
28340 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
28350 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
28360 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a  _bind_value()]..
28370 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
28380 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c  value_blob | sql
28390 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
283a0 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  )] family of.** 
283b0 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
283c0 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c  re protected sql
283d0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
283e0 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ts..*/.typedef s
283f0 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65  truct Mem sqlite
28400 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20  3_value;../*.** 
28410 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75  CAPI3REF: SQL Fu
28420 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f  nction Context O
28430 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
28440 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68  context in which
28450 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   an SQL function
28460 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f   executes is sto
28470 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c  red in an.** sql
28480 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
28490 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72  ect.  ^A pointer
284a0 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63   to an sqlite3_c
284b0 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a  ontext object.**
284c0 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74   is always first
284d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61   parameter to [a
284e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
284f0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
28500 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  ]..** The applic
28510 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
28520 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
28530 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70  mentation will p
28540 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e  ass this.** poin
28550 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f  ter through into
28560 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
28570 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20  e3_result_int | 
28580 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29  sqlite3_result()
28590 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61  ],.** [sqlite3_a
285a0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
285b0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73  ()], [sqlite3_us
285c0 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b  er_data()],.** [
285d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
285e0 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73  db_handle()], [s
285f0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
28600 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72  ta()],.** and/or
28610 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
28620 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70  xdata()]..*/.typ
28630 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
28640 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69  te3_context sqli
28650 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a  te3_context;../*
28660 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69  .** CAPI3REF: Bi
28670 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20  nding Values To 
28680 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
28690 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  nts.** KEYWORDS:
286a0 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
286b0 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
286c0 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  rs} {host parame
286d0 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59  ter name}.** KEY
286e0 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61  WORDS: {SQL para
286f0 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61  meter} {SQL para
28700 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74  meters} {paramet
28710 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a  er binding}.**.*
28720 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73  * ^(In the SQL s
28730 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e  tatement text in
28740 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
28750 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
28760 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a  d its variants,.
28770 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20  ** literals may 
28780 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  be replaced by a
28790 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61   [parameter] tha
287a0 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66  t matches one of
287b0 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65   following.** te
287c0 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  mplates:.**.** <
287d0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a  ul>.** <li>  ?.*
287e0 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20  * <li>  ?NNN.** 
287f0 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c  <li>  :VVV.** <l
28800 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  @VVV.** <li>
28810 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a    $VVV.** </ul>.
28820 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d  **.** In the tem
28830 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e  plates above, NN
28840 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  N represents an 
28850 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c  integer literal,
28860 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72  .** and VVV repr
28870 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e  esents an alphan
28880 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65  umeric identifie
28890 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65  r.)^  ^The value
288a0 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61  s of these.** pa
288b0 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63  rameters (also c
288c0 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61  alled "host para
288d0 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20  meter names" or 
288e0 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22  "SQL parameters"
288f0 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20  ).** can be set 
28900 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
28910 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
28920 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65  nes defined here
28930 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
28940 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
28950 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
28960 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20  *() routines is 
28970 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e  always.** a poin
28980 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
28990 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
289a0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a   returned from.*
289b0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
289c0 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20  re_v2()] or its 
289d0 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  variants..**.** 
289e0 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
289f0 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
28a00 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72  x of the SQL par
28a10 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74  ameter to be set
28a20 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ..** ^The leftmo
28a30 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  st SQL parameter
28a40 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
28a50 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73   1.  ^When the s
28a60 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c  ame named.** SQL
28a70 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73   parameter is us
28a80 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  ed more than onc
28a90 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  e, second and su
28aa0 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75  bsequent.** occu
28ab0 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65  rrences have the
28ac0 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74   same index as t
28ad0 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65  he first occurre
28ae0 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64  nce..** ^The ind
28af0 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72  ex for named par
28b00 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c  ameters can be l
28b10 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74  ooked up using t
28b20 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  he.** [sqlite3_b
28b30 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
28b40 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65  dex()] API if de
28b50 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64  sired.  ^The ind
28b60 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22  ex.** for "?NNN"
28b70 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74   parameters is t
28b80 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e  he value of NNN.
28b90 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c  .** ^The NNN val
28ba0 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65  ue must be betwe
28bb0 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71  en 1 and the [sq
28bc0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
28bd0 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c  * parameter [SQL
28be0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
28bf0 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61  LE_NUMBER] (defa
28c00 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e  ult value: 999).
28c10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
28c20 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
28c30 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20  e value to bind 
28c40 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
28c50 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69  ..** ^If the thi
28c60 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
28c70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
28c80 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  t() or sqlite3_b
28c90 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  ind_text16().** 
28ca0 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
28cb0 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c  blob() is a NULL
28cc0 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
28cd0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
28ce0 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64  er.** is ignored
28cf0 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73   and the end res
28d00 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65 20  ult is the same 
28d10 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  as sqlite3_bind_
28d20 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28  null()..**.** ^(
28d30 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65  In those routine
28d40 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f  s that have a fo
28d50 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69  urth argument, i
28d60 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  ts value is the.
28d70 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  ** number of byt
28d80 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  es in the parame
28d90 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61  ter.  To be clea
28da0 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  r: the value is 
28db0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
28dc0 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e   <u>bytes</u> in
28dd0 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20   the value, not 
28de0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
28df0 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e  aracters.)^.** ^
28e00 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
28e10 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
28e20 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f  e3_bind_text() o
28e30 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
28e40 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65  ext16().** is ne
28e50 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
28e60 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
28e70 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20  tring is.** the 
28e80 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
28e90 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
28ea0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
28eb0 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74  .** If the fourt
28ec0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
28ed0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
28ee0 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  () is negative, 
28ef0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61  then.** the beha
28f00 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
28f10 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e  d..** If a non-n
28f20 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70  egative fourth p
28f30 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76  arameter is prov
28f40 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f  ided to sqlite3_
28f50 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f  bind_text().** o
28f60 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
28f70 65 78 74 31 36 28 29 20 74 68 65 6e 20 74 68 61  ext16() then tha
28f80 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
28f90 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66   be the byte off
28fa0 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65  set.** where the
28fb0 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20   NUL terminator 
28fc0 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75  would occur assu
28fd0 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20  ming the string 
28fe0 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d  were NUL.** term
28ff0 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20  inated.  If any 
29000 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f  NUL characters o
29010 63 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66  ccur at byte off
29020 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a  sets less than .
29030 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ** the value of 
29040 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
29050 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65  eter then the re
29060 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76  sulting string v
29070 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  alue will.** con
29080 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55  tain embedded NU
29090 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  Ls.  The result 
290a0 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69  of expressions i
290b0 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73  nvolving strings
290c0 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65  .** with embedde
290d0 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69  d NULs is undefi
290e0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
290f0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74  fifth argument t
29100 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
29110 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62  lob(), sqlite3_b
29120 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a  ind_text(), and.
29130 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ** sqlite3_bind_
29140 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65  text16() is a de
29150 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f  structor used to
29160 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
29170 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e  BLOB or.** strin
29180 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68  g after SQLite h
29190 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
291a0 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72   it.  ^The destr
291b0 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a  uctor is called.
291c0 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ** to dispose of
291d0 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72   the BLOB or str
291e0 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
291f0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
29200 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20  bind_blob(),.** 
29210 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
29220 74 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  t(), or sqlite3_
29230 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 66 61  bind_text16() fa
29240 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68  ils.  .** ^If th
29250 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
29260 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69   is.** the speci
29270 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  al value [SQLITE
29280 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53  _STATIC], then S
29290 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
292a0 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d  at the.** inform
292b0 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74  ation is in stat
292c0 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70  ic, unmanaged sp
292d0 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
292e0 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65   need to be free
292f0 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  d..** ^If the fi
29300 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73  fth argument has
29310 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49   the value [SQLI
29320 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74  TE_TRANSIENT], t
29330 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61  hen.** SQLite ma
29340 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76  kes its own priv
29350 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
29360 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79  data immediately
29370 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20  , before.** the 
29380 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
29390 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
293a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
293b0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
293c0 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e  ob() routine bin
293d0 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e  ds a BLOB of len
293e0 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73  gth N that.** is
293f0 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72   filled with zer
29400 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f  oes.  ^A zeroblo
29410 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61  b uses a fixed a
29420 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a  mount of memory.
29430 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65  ** (just an inte
29440 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20  ger to hold its 
29450 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69  size) while it i
29460 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65  s being processe
29470 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20  d..** Zeroblobs 
29480 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20  are intended to 
29490 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f  serve as placeho
294a0 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20  lders for BLOBs 
294b0 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  whose.** content
294c0 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65   is later writte
294d0 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
294e0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20  te3_blob_open | 
294f0 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42  incremental BLOB
29500 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a   I/O] routines..
29510 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76  ** ^A negative v
29520 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72  alue for the zer
29530 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e  oblob results in
29540 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
29550 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  LOB..**.** ^If a
29560 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ny of the sqlite
29570 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
29580 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77  nes are called w
29590 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
295a0 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70  er.** for the [p
295b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
295c0 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65  t] or with a pre
295d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
295e0 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71  for which.** [sq
295f0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
29600 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f  s been called mo
29610 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e  re recently than
29620 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
29630 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  )],.** then the 
29640 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e  call will return
29650 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
29660 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65  .  If any sqlite
29670 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75  3_bind_().** rou
29680 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61  tine is passed a
29690 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
296a0 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62  ment] that has b
296b0 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74  een finalized, t
296c0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20  he.** result is 
296d0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
296e0 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a  obably harmful..
296f0 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20  **.** ^Bindings 
29700 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20  are not cleared 
29710 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
29720 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65  reset()] routine
29730 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61  ..** ^Unbound pa
29740 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74  rameters are int
29750 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c  erpreted as NULL
29760 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
29770 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74  ite3_bind_* rout
29780 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
29790 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
297a0 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72  ss or an.** [err
297b0 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74  or code] if anyt
297c0 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e  hing goes wrong.
297d0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e  .** ^[SQLITE_RAN
297e0 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  GE] is returned 
297f0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
29800 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74  .** index is out
29810 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51   of range.  ^[SQ
29820 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72  LITE_NOMEM] is r
29830 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f  eturned if mallo
29840 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a  c() fails..**.**
29850 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
29860 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
29870 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20  er_count()],.** 
29880 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
29890 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
298a0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
298b0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
298c0 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ex()]..*/.int sq
298d0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
298e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
298f0 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
29900 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
29910 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
29920 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65  ite3_bind_double
29930 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29940 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e  int, double);.in
29950 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
29960 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
29970 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74  , int, int);.int
29980 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
29990 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
299a0 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
299b0 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69  int64);.int sqli
299c0 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71  te3_bind_null(sq
299d0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
299e0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
299f0 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ind_text(sqlite3
29a00 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
29a10 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c  st char*, int n,
29a20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
29a30 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
29a40 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  nd_text16(sqlite
29a50 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
29a60 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
29a70 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
29a80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
29a90 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  d_value(sqlite3_
29aa0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
29ab0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t sqlite3_value*
29ac0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
29ad0 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ind_zeroblob(sql
29ae0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
29af0 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
29b00 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
29b10 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65   Of SQL Paramete
29b20 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  rs.**.** ^This r
29b30 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73  outine can be us
29b40 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
29b50 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61  umber of [SQL pa
29b60 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20  rameters].** in 
29b70 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
29b80 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72  ement].  SQL par
29b90 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65  ameters are toke
29ba0 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72  ns of the.** for
29bb0 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22  m "?", "?NNN", "
29bc0 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f  :AAA", "$AAA", o
29bd0 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65  r "@AAA" that se
29be0 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68  rve as.** placeh
29bf0 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65  olders for value
29c00 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69  s that are [sqli
29c10 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
29c20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65  bound].** to the
29c30 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61   parameters at a
29c40 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a   later time..**.
29c50 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e  ** ^(This routin
29c60 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72  e actually retur
29c70 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  ns the index of 
29c80 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67  the largest (rig
29c90 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d  htmost).** param
29ca0 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f  eter. For all fo
29cb0 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c  rms except ?NNN,
29cc0 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65   this will corre
29cd0 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20  spond to the.** 
29ce0 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65  number of unique
29cf0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66   parameters.  If
29d00 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
29d10 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65  he ?NNN form are
29d20 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20   used,.** there 
29d30 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74  may be gaps in t
29d40 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a  he list.)^.**.**
29d50 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
29d60 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
29d70 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
29d80 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
29d90 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
29da0 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
29db0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
29dc0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69  r_index()]..*/.i
29dd0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
29de0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
29df0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
29e00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29e10 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20   Name Of A Host 
29e20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20  Parameter.**.** 
29e30 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
29e40 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
29e50 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (P,N) interface 
29e60 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
29e70 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20  ame of the N-th 
29e80 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
29e90 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  in the [prepared
29ea0 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a   statement] P..*
29eb0 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65  * ^(SQL paramete
29ec0 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
29ed0 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
29ee0 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
29ef0 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61  AA".** have a na
29f00 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20  me which is the 
29f10 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72  string "?NNN" or
29f20 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
29f30 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72  " or "$AAA".** r
29f40 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
29f50 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
29f60 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20  the initial ":" 
29f70 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72  or "$" or "@" or
29f80 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75   "?".** is inclu
29f90 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  ded as part of t
29fa0 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50  he name.)^.** ^P
29fb0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
29fc0 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75   form "?" withou
29fd0 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  t a following in
29fe0 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61  teger have no na
29ff0 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65  me.** and are re
2a000 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61  ferred to as "na
2a010 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e  meless" or "anon
2a020 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73  ymous parameters
2a030 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  "..**.** ^The fi
2a040 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74  rst host paramet
2a050 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
2a060 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a  of 1, not 0..**.
2a070 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65  ** ^If the value
2a080 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e   N is out of ran
2a090 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74  ge or if the N-t
2a0a0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
2a0b0 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e  * nameless, then
2a0c0 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
2a0d0 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  d.  ^The returne
2a0e0 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61  d string is.** a
2a0f0 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65  lways in UTF-8 e
2a100 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20  ncoding even if 
2a110 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  the named parame
2a120 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69  ter was.** origi
2a130 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20  nally specified 
2a140 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71  as UTF-16 in [sq
2a150 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2a160 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
2a170 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2a180 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
2a190 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
2a1a0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
2a1b0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
2a1c0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2a1d0 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
2a1e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2a1f0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2a200 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ()]..*/.const ch
2a210 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64  ar *sqlite3_bind
2a220 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
2a230 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2a240 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2a250 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41  3REF: Index Of A
2a260 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20   Parameter With 
2a270 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a  A Given Name.**.
2a280 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69  ** ^Return the i
2a290 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70  ndex of an SQL p
2a2a0 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69  arameter given i
2a2b0 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a  ts name.  ^The.*
2a2c0 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65  * index value re
2a2d0 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62  turned is suitab
2a2e0 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68  le for use as th
2a2f0 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61  e second.** para
2a300 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
2a310 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2a320 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41  te3_bind()].  ^A
2a330 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75   zero.** is retu
2a340 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68  rned if no match
2a350 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  ing parameter is
2a360 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61   found.  ^The pa
2a370 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20  rameter.** name 
2a380 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e  must be given in
2a390 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74   UTF-8 even if t
2a3a0 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
2a3b0 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65  ement.** was pre
2a3c0 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31  pared from UTF-1
2a3d0 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71  6 text using [sq
2a3e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2a3f0 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
2a400 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2a410 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2a420 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
2a430 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2a440 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
2a450 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2a460 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2a470 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ndex()]..*/.int 
2a480 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2a490 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c  ameter_index(sql
2a4a0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73  ite3_stmt*, cons
2a4b0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
2a4c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2a4d0 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69   Reset All Bindi
2a4e0 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65  ngs On A Prepare
2a4f0 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  d Statement.**.*
2a500 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74  * ^Contrary to t
2a510 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20  he intuition of 
2a520 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72  many, [sqlite3_r
2a530 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74  eset()] does not
2a540 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73   reset.** the [s
2a550 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2a560 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20   | bindings] on 
2a570 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2a580 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20  ement]..** ^Use 
2a590 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20  this routine to 
2a5a0 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70  reset all host p
2a5b0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c  arameters to NUL
2a5c0 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  L..*/.int sqlite
2a5d0 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
2a5e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2a5f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2a600 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75  : Number Of Colu
2a610 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mns In A Result 
2a620 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  Set.**.** ^Retur
2a630 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  n the number of 
2a640 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
2a650 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e  esult set return
2a660 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72  ed by the.** [pr
2a670 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a680 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ]. ^This routine
2a690 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53   returns 0 if pS
2a6a0 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a  tmt is an SQL.**
2a6b0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
2a6c0 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20  does not return 
2a6d0 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c  data (for exampl
2a6e0 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a  e an [UPDATE])..
2a6f0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2a700 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f  [sqlite3_data_co
2a710 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71  unt()].*/.int sq
2a720 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
2a730 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
2a740 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2a750 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e  CAPI3REF: Column
2a760 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75   Names In A Resu
2a770 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  lt Set.**.** ^Th
2a780 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
2a790 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73  urn the name ass
2a7a0 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69  igned to a parti
2a7b0 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  cular column.** 
2a7c0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
2a7d0 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
2a7e0 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65  statement.  ^The
2a7f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a800 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  name().** interf
2a810 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2a820 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
2a830 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
2a840 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73   string.** and s
2a850 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2a860 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61  me16() returns a
2a870 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
2a880 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
2a890 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
2a8a0 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
2a8b0 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72  meter is the [pr
2a8c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a8d0 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d  ].** that implem
2a8e0 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54  ents the [SELECT
2a8f0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68  ] statement. ^Th
2a900 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2a910 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c  er is the.** col
2a920 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68  umn number.  ^Th
2a930 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
2a940 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a  n is number 0..*
2a950 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  *.** ^The return
2a960 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  ed string pointe
2a970 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  r is valid until
2a980 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65   either the [pre
2a990 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a9a0 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64  .** is destroyed
2a9b0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   by [sqlite3_fin
2a9c0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
2a9d0 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
2a9e0 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
2a9f0 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
2aa00 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
2aa10 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2aa20 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
2aa30 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
2aa40 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63  until the next c
2aa50 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
2aa60 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20  3_column_name() 
2aa70 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
2aa80 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68  n_name16() on th
2aa90 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a  e same column..*
2aaa0 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  *.** ^If sqlite3
2aab0 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20  _malloc() fails 
2aac0 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65  during the proce
2aad0 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20  ssing of either 
2aae0 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20  routine.** (for 
2aaf0 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61  example during a
2ab00 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d   conversion from
2ab10 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36   UTF-8 to UTF-16
2ab20 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  ) then a.** NULL
2ab30 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
2ab40 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
2ab50 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c   name of a resul
2ab60 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20  t column is the 
2ab70 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53  value of the "AS
2ab80 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20  " clause for.** 
2ab90 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20  that column, if 
2aba0 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63  there is an AS c
2abb0 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65  lause.  If there
2abc0 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65   is no AS clause
2abd0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d  .** then the nam
2abe0 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e of the column 
2abf0 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61  is unspecified a
2ac00 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72  nd may change fr
2ac10 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73  om.** one releas
2ac20 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74  e of SQLite to t
2ac30 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73  he next..*/.cons
2ac40 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2ac50 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69  column_name(sqli
2ac60 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
2ac70 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2ac80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2ac90 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
2aca0 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a  t*, int N);../*.
2acb0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75  ** CAPI3REF: Sou
2acc0 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41  rce Of Data In A
2acd0 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
2ace0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
2acf0 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65  nes provide a me
2ad00 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ans to determine
2ad10 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74   the database, t
2ad20 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62  able, and.** tab
2ad30 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69  le column that i
2ad40 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20  s the origin of 
2ad50 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73  a particular res
2ad60 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a  ult column in.**
2ad70 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2ad80 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ent..** ^The nam
2ad90 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
2ada0 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f  e or table or co
2adb0 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75  lumn can be retu
2adc0 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65  rned as.** eithe
2add0 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46  r a UTF-8 or UTF
2ade0 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68  -16 string.  ^Th
2adf0 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75  e _database_ rou
2ae00 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tines return.** 
2ae10 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
2ae20 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72  e, the _table_ r
2ae30 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
2ae40 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61  he table name, a
2ae50 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  nd.** the origin
2ae60 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
2ae70 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d  n the column nam
2ae80 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  e..** ^The retur
2ae90 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61  ned string is va
2aea0 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70  lid until the [p
2aeb0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2aec0 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a  t] is destroyed.
2aed0 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
2aee0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
2aef0 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
2af00 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
2af10 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
2af20 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
2af30 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2af40 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
2af50 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
2af60 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  * or until the s
2af70 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
2af80 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20  is requested.** 
2af90 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65  again in a diffe
2afa0 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  rent encoding..*
2afb0 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20  *.** ^The names 
2afc0 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65  returned are the
2afd0 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69   original un-ali
2afe0 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68  ased names of th
2aff0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74  e.** database, t
2b000 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e  able, and column
2b010 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
2b020 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
2b030 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
2b040 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
2b050 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54  tatement]..** ^T
2b060 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
2b070 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
2b080 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20  n about the Nth 
2b090 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65  result column re
2b0a0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65  turned by.** the
2b0b0 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72   statement, wher
2b0c0 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
2b0d0 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  d function argum
2b0e0 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  ent..** ^The lef
2b0f0 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  t-most column is
2b100 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68   column 0 for th
2b110 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
2b120 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20  .** ^If the Nth 
2b130 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
2b140 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  by the statement
2b150 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f   is an expressio
2b160 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79  n or.** subquery
2b170 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f   and is not a co
2b180 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e  lumn value, then
2b190 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75   all of these fu
2b1a0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a  nctions return.*
2b1b0 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20  * NULL.  ^These 
2b1c0 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c  routine might al
2b1d0 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69  so return NULL i
2b1e0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
2b1f0 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f  ation error.** o
2b200 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69  ccurs.  ^Otherwi
2b210 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20  se, they return 
2b220 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2b230 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
2b240 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20  e, table,.** or 
2b250 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72  column that quer
2b260 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  y result column 
2b270 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72  was extracted fr
2b280 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69  om..**.** ^As wi
2b290 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c  th all other SQL
2b2a0 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20  ite APIs, those 
2b2b0 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20  whose names end 
2b2c0 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e  with "16" return
2b2d0 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  .** UTF-16 encod
2b2e0 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74  ed strings and t
2b2f0 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f  he other functio
2b300 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e  ns return UTF-8.
2b310 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50  .**.** ^These AP
2b320 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69  Is are only avai
2b330 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62  lable if the lib
2b340 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65  rary was compile
2b350 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
2b360 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c  QLITE_ENABLE_COL
2b370 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d  UMN_METADATA] C-
2b380 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d  preprocessor sym
2b390 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  bol..**.** If tw
2b3a0 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
2b3b0 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
2b3c0 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  re of these rout
2b3d0 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65  ines against the
2b3e0 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65   same.** prepare
2b3f0 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  d statement and 
2b400 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61  column at the sa
2b410 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
2b420 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20   results are.** 
2b430 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2b440 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
2b450 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
2b460 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c   or more.** [sql
2b470 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
2b480 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75  base_name | colu
2b490 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65  mn metadata inte
2b4a0 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74  rfaces].** for t
2b4b0 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  he same [prepare
2b4c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64  d statement] and
2b4d0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a   result column.*
2b4e0 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  * at the same ti
2b4f0 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
2b500 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
2b510 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  d..*/.const char
2b520 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2b530 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73  _database_name(s
2b540 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2b550 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2b560 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
2b570 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71  tabase_name16(sq
2b580 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2b590 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
2b5a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
2b5b0 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  le_name(sqlite3_
2b5c0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
2b5d0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2b5e0 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
2b5f0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2b600 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
2b610 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2b620 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73  mn_origin_name(s
2b630 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2b640 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2b650 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
2b660 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  igin_name16(sqli
2b670 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2b680 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b690 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79   Declared Dataty
2b6a0 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65  pe Of A Query Re
2b6b0 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  sult.**.** ^(The
2b6c0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2b6d0 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
2b6e0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49  statement]..** I
2b6f0 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74  f this statement
2b700 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   is a [SELECT] s
2b710 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65  tatement and the
2b720 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
2b730 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72  he.** returned r
2b740 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61  esult set of tha
2b750 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20  t [SELECT] is a 
2b760 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f  table column (no
2b770 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  t an.** expressi
2b780 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20  on or subquery) 
2b790 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65  then the declare
2b7a0 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61  d type of the ta
2b7b0 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73  ble.** column is
2b7c0 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49   returned.)^  ^I
2b7d0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
2b7e0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2b7f0 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72  et is an.** expr
2b800 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
2b810 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20  ry, then a NULL 
2b820 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
2b830 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ned..** ^The ret
2b840 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
2b850 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63  always UTF-8 enc
2b860 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f  oded..**.** ^(Fo
2b870 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e  r example, given
2b880 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
2b890 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41  hema:.**.** CREA
2b8a0 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56  TE TABLE t1(c1 V
2b8b0 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61  ARIANT);.**.** a
2b8c0 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  nd the following
2b8d0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
2b8e0 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a   compiled:.**.**
2b8f0 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20   SELECT c1 + 1, 
2b900 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a  c1 FROM t1;.**.*
2b910 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  * this routine w
2b920 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
2b930 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22  string "VARIANT"
2b940 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20   for the second 
2b950 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e  result.** column
2b960 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e   (i==1), and a N
2b970 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ULL pointer for 
2b980 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74  the first result
2b990 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29   column (i==0).)
2b9a0 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ^.**.** ^SQLite 
2b9b0 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e  uses dynamic run
2b9c0 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e  -time typing.  ^
2b9d0 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20  So just because 
2b9e0 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64  a column.** is d
2b9f0 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61  eclared to conta
2ba00 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  in a particular 
2ba10 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65  type does not me
2ba20 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64  an that the.** d
2ba30 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68  ata stored in th
2ba40 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20  at column is of 
2ba50 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
2ba60 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  e.  SQLite is.**
2ba70 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c   strongly typed,
2ba80 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20   but the typing 
2ba90 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73  is dynamic not s
2baa0 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a  tatic.  ^Type.**
2bab0 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77   is associated w
2bac0 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76  ith individual v
2bad0 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20  alues, not with 
2bae0 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a  the containers.*
2baf0 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74  * used to hold t
2bb00 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a  hose values..*/.
2bb10 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2bb20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
2bb30 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
2bb40 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
2bb50 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2bb60 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71  mn_decltype16(sq
2bb70 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2bb80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2bb90 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53  F: Evaluate An S
2bba0 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  QL Statement.**.
2bbb0 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70  ** After a [prep
2bbc0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2bbd0 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65  has been prepare
2bbe0 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a  d using either.*
2bbf0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2bc00 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
2bc10 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2bc20 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  2()] or one of t
2bc30 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
2bc40 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
2bc50 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b  _prepare()] or [
2bc60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2bc70 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74  6()], this funct
2bc80 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63  ion.** must be c
2bc90 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72  alled one or mor
2bca0 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75  e times to evalu
2bcb0 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ate the statemen
2bcc0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74  t..**.** The det
2bcd0 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61  ails of the beha
2bce0 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69  vior of the sqli
2bcf0 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72  te3_step() inter
2bd00 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f  face depend.** o
2bd10 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74  n whether the st
2bd20 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70  atement was prep
2bd30 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e  ared using the n
2bd40 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66  ewer "v2" interf
2bd50 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ace.** [sqlite3_
2bd60 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
2bd70 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
2bd80 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68  re16_v2()] or th
2bd90 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a  e older legacy.*
2bda0 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c  * interface [sql
2bdb0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
2bdc0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
2bdd0 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20  pare16()].  The 
2bde0 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65  use of the.** ne
2bdf0 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  w "v2" interface
2be00 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
2be10 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74  for new applicat
2be20 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67  ions but the leg
2be30 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
2be40 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74   will continue t
2be50 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a  o be supported..
2be60 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65  **.** ^In the le
2be70 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
2be80 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
2be90 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20   will be either 
2bea0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a  [SQLITE_BUSY],.*
2beb0 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  * [SQLITE_DONE],
2bec0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b   [SQLITE_ROW], [
2bed0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f  SQLITE_ERROR], o
2bee0 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  r [SQLITE_MISUSE
2bef0 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20  ]..** ^With the 
2bf00 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20  "v2" interface, 
2bf10 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72  any of the other
2bf20 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20   [result codes] 
2bf30 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
2bf40 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69  result codes] mi
2bf50 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20  ght be returned 
2bf60 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  as well..**.** ^
2bf70 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65  [SQLITE_BUSY] me
2bf80 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74  ans that the dat
2bf90 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73  abase engine was
2bfa0 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69   unable to acqui
2bfb0 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  re the.** databa
2bfc0 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64  se locks it need
2bfd0 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e  s to do its job.
2bfe0 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d    ^If the statem
2bff0 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54  ent is a [COMMIT
2c000 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f  ].** or occurs o
2c010 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70  utside of an exp
2c020 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
2c030 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20  n, then you can 
2c040 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61  retry the.** sta
2c050 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20  tement.  If the 
2c060 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74  statement is not
2c070 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20   a [COMMIT] and 
2c080 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e  occurs within an
2c090 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61  .** explicit tra
2c0a0 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f  nsaction then yo
2c0b0 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63  u should rollbac
2c0c0 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  k the transactio
2c0d0 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74  n before.** cont
2c0e0 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  inuing..**.** ^[
2c0f0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61  SQLITE_DONE] mea
2c100 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74  ns that the stat
2c110 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68  ement has finish
2c120 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20  ed executing.** 
2c130 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73  successfully.  s
2c140 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
2c150 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
2c160 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73  ed again on this
2c170 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
2c180 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73  ine without firs
2c190 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
2c1a0 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72  e3_reset()] to r
2c1b0 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c  eset the virtual
2c1c0 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b  .** machine back
2c1d0 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20   to its initial 
2c1e0 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  state..**.** ^If
2c1f0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2c200 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65  nt being execute
2c210 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61  d returns any da
2c220 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  ta, then [SQLITE
2c230 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75  _ROW].** is retu
2c240 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61  rned each time a
2c250 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61   new row of data
2c260 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72   is ready for pr
2c270 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a  ocessing by the.
2c280 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76  ** caller. The v
2c290 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63  alues may be acc
2c2a0 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20  essed using the 
2c2b0 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
2c2c0 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71  unctions]..** sq
2c2d0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20  lite3_step() is 
2c2e0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20  called again to 
2c2f0 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78  retrieve the nex
2c300 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a  t row of data..*
2c310 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52  *.** ^[SQLITE_ER
2c320 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ROR] means that 
2c330 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72  a run-time error
2c340 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73   (such as a cons
2c350 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74  traint.** violat
2c360 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65  ion) has occurre
2c370 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  d.  sqlite3_step
2c380 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
2c390 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
2c3a0 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65  .** the VM. More
2c3b0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79   information may
2c3c0 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c   be found by cal
2c3d0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72  ling [sqlite3_er
2c3e0 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74  rmsg()]..** ^Wit
2c3f0 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  h the legacy int
2c400 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73  erface, a more s
2c410 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
2c420 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c  de (for example,
2c430 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
2c440 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  RRUPT], [SQLITE_
2c450 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45  SCHEMA], [SQLITE
2c460 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73  _CORRUPT], and s
2c470 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20  o forth).** can 
2c480 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63  be obtained by c
2c490 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2c4a0 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a  reset()] on the.
2c4b0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2c4c0 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68  tement].  ^In th
2c4d0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2c4e0 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70  ,.** the more sp
2c4f0 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
2c500 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69  e is returned di
2c510 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65  rectly by sqlite
2c520 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_step()..**.** 
2c530 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
2c540 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74  means that the t
2c550 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20  his routine was 
2c560 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72  called inappropr
2c570 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61  iately..** Perha
2c580 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64  ps it was called
2c590 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
2c5a0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
2c5b0 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62  has.** already b
2c5c0 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  een [sqlite3_fin
2c5d0 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
2c5e0 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61  d] or on one tha
2c5f0 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75  t had.** previou
2c600 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51  sly returned [SQ
2c610 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b  LITE_ERROR] or [
2c620 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f  SQLITE_DONE].  O
2c630 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65  r it could.** be
2c640 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
2c650 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
2c660 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62   connection is b
2c670 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f  eing used by two
2c680 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65   or.** more thre
2c690 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
2c6a0 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a  moment in time..
2c6b0 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65  **.** For all ve
2c6c0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
2c6d0 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75   up to and inclu
2c6e0 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61  ding 3.6.23.1, a
2c6f0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
2c700 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61  ite3_reset()] wa
2c710 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72  s required after
2c720 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2c730 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e  returned anythin
2c740 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20  g.** other than 
2c750 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66  [SQLITE_ROW] bef
2c760 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65  ore any subseque
2c770 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  nt invocation of
2c780 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
2c790 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20  ().  Failure to 
2c7a0 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  reset the prepar
2c7b0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  ed statement usi
2c7c0 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
2c7d0 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72  reset()] would r
2c7e0 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c  esult in an [SQL
2c7f0 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75  ITE_MISUSE] retu
2c800 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74  rn from.** sqlit
2c810 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20  e3_step().  But 
2c820 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e  after version 3.
2c830 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f  6.23.1, sqlite3_
2c840 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20  step() began.** 
2c850 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2c860 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61  _reset()] automa
2c870 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20  tically in this 
2c880 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74  circumstance rat
2c890 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75  her.** than retu
2c8a0 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49  rning [SQLITE_MI
2c8b0 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20  SUSE].  This is 
2c8c0 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61  not considered a
2c8d0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a   compatibility.*
2c8e0 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20  * break because 
2c8f0 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  any application 
2c900 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76  that ever receiv
2c910 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53  es an SQLITE_MIS
2c920 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20  USE error.** is 
2c930 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69  broken by defini
2c940 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49  tion.  The [SQLI
2c950 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45  TE_OMIT_AUTORESE
2c960 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  T] compile-time 
2c970 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65  option.** can be
2c980 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65   used to restore
2c990 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61   the legacy beha
2c9a0 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47  vior..**.** <b>G
2c9b0 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41  oofy Interface A
2c9c0 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65  lert:</b> In the
2c9d0 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
2c9e0 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  e, the sqlite3_s
2c9f0 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77  tep().** API alw
2ca00 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65  ays returns a ge
2ca10 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65  neric error code
2ca20 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
2ca30 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a  , following any.
2ca40 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74  ** error other t
2ca50 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  han [SQLITE_BUSY
2ca60 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49  ] and [SQLITE_MI
2ca70 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74  SUSE].  You must
2ca80 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
2ca90 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
2caa0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2cab0 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  )] in order to f
2cac0 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  ind one of the.*
2cad0 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  * specific [erro
2cae0 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65  r codes] that be
2caf0 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74  tter describes t
2cb00 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20  he error..** We 
2cb10 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20  admit that this 
2cb20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67  is a goofy desig
2cb30 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20  n.  The problem 
2cb40 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a  has been fixed.*
2cb50 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20  * with the "v2" 
2cb60 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79  interface.  If y
2cb70 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f  ou prepare all o
2cb80 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65  f your SQL state
2cb90 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65  ments.** using e
2cba0 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
2cbb0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2cbc0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2cbd0 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64  16_v2()] instead
2cbe0 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63  .** of the legac
2cbf0 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
2cc00 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
2cc10 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
2cc20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74  interfaces,.** t
2cc30 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65  hen the more spe
2cc40 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
2cc50 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64  es] are returned
2cc60 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20   directly.** by 
2cc70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
2cc80 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   The use of the 
2cc90 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
2cca0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  s recommended..*
2ccb0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
2ccc0 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ep(sqlite3_stmt*
2ccd0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2cce0 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f  EF: Number of co
2ccf0 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c  lumns in a resul
2cd00 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  t set.**.** ^The
2cd10 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2cd20 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65  unt(P) interface
2cd30 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2cd40 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2cd50 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  n the.** current
2cd60 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
2cd70 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61  lt set of [prepa
2cd80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
2cd90 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65  ..** ^If prepare
2cda0 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f  d statement P do
2cdb0 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75  es not have resu
2cdc0 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74  lts ready to ret
2cdd0 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c  urn.** (via call
2cde0 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  s to the [sqlite
2cdf0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73  3_column_int | s
2ce00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28  qlite3_column_*(
2ce10 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  )] of.** interfa
2ce20 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65  ces) then sqlite
2ce30 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
2ce40 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54  returns 0..** ^T
2ce50 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
2ce60 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
2ce70 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20   also returns 0 
2ce80 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70  if P is a NULL p
2ce90 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  ointer..** ^The 
2cea0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2ceb0 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65  nt(P) routine re
2cec0 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70  turns 0 if the p
2ced0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a  revious call to.
2cee0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2cef0 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53  ](P) returned [S
2cf00 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54  QLITE_DONE].  ^T
2cf10 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
2cf20 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c  count(P).** will
2cf30 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f   return non-zero
2cf40 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c   if previous cal
2cf50 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
2cf60 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a  ep](P) returned.
2cf70 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ** [SQLITE_ROW],
2cf80 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63   except in the c
2cf90 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47  ase of the [PRAG
2cfa0 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76  MA incremental_v
2cfb0 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20  acuum].** where 
2cfc0 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
2cfd0 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63  s zero since eac
2cfe0 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d  h step of that m
2cff0 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61  ulti-step.** pra
2d000 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f  gma returns 0 co
2d010 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a  lumns of data..*
2d020 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2d030 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
2d040 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73  ount()].*/.int s
2d050 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2d060 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
2d070 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2d080 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65  API3REF: Fundame
2d090 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a  ntal Datatypes.*
2d0a0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
2d0b0 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28  TE_TEXT.**.** ^(
2d0c0 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53  Every value in S
2d0d0 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66  QLite has one of
2d0e0 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61   five fundamenta
2d0f0 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a  l datatypes:.**.
2d100 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
2d110 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
2d120 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34  teger.** <li> 64
2d130 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69  -bit IEEE floati
2d140 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a  ng point number.
2d150 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a  ** <li> string.*
2d160 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c  * <li> BLOB.** <
2d170 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c  li> NULL.** </ul
2d180 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  >)^.**.** These 
2d190 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f  constants are co
2d1a0 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20  des for each of 
2d1b0 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a  those types..**.
2d1c0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  ** Note that the
2d1d0 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e   SQLITE_TEXT con
2d1e0 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75  stant was also u
2d1f0 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65  sed in SQLite ve
2d200 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61  rsion 2.** for a
2d210 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66   completely diff
2d220 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20  erent meaning.  
2d230 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69  Software that li
2d240 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68  nks against both
2d250 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
2d260 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20  on 2 and SQLite 
2d270 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64  version 3 should
2d280 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58   use SQLITE3_TEX
2d290 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45  T, not.** SQLITE
2d2a0 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e  _TEXT..*/.#defin
2d2b0 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52  e SQLITE_INTEGER
2d2c0 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
2d2d0 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64  TE_FLOAT    2.#d
2d2e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f  efine SQLITE_BLO
2d2f0 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20  B     4.#define 
2d300 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20  SQLITE_NULL     
2d310 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  5.#ifdef SQLITE_
2d320 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c  TEXT.# undef SQL
2d330 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23  ITE_TEXT.#else.#
2d340 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54   define SQLITE_T
2d350 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66  EXT     3.#endif
2d360 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33  .#define SQLITE3
2d370 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a  _TEXT     3../*.
2d380 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
2d390 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20  ult Values From 
2d3a0 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f  A Query.** KEYWO
2d3b0 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63  RDS: {column acc
2d3c0 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  ess functions}.*
2d3d0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2d3e0 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65  nes form the "re
2d3f0 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66  sult set" interf
2d400 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ace..**.** ^Thes
2d410 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
2d420 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
2d430 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c  out a single col
2d440 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  umn of the curre
2d450 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77  nt.** result row
2d460 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49   of a query.  ^I
2d470 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65  n every case the
2d480 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
2d490 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  is a pointer.** 
2d4a0 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  to the [prepared
2d4b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
2d4c0 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61   is being evalua
2d4d0 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ted (the [sqlite
2d4e0 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74  3_stmt*].** that
2d4f0 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72   was returned fr
2d500 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  om [sqlite3_prep
2d510 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  are_v2()] or one
2d520 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73   of its variants
2d530 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63  ).** and the sec
2d540 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
2d550 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
2d560 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63   column for whic
2d570 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  h information.**
2d580 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
2d590 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ned. ^The leftmo
2d5a0 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  st column of the
2d5b0 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20   result set has 
2d5c0 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20  the index 0..** 
2d5d0 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63  ^The number of c
2d5e0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
2d5f0 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65  sult can be dete
2d600 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20  rmined using.** 
2d610 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2d620 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  count()]..**.** 
2d630 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
2d640 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75  ment does not cu
2d650 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f  rrently point to
2d660 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72   a valid row, or
2d670 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   if the.** colum
2d680 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  n index is out o
2d690 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73  f range, the res
2d6a0 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
2d6b0 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
2d6c0 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  nes may only be 
2d6d0 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20  called when the 
2d6e0 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
2d6f0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
2d700 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
2d710 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
2d720 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a  ] and neither.**
2d730 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2d740 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )] nor [sqlite3_
2d750 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65  finalize()] have
2d760 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62   been called sub
2d770 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66  sequently..** If
2d780 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
2d790 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
2d7a0 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
2d7b0 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
2d7c0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2d7d0 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73  e()] or after [s
2d7e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
2d7f0 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73  as returned.** s
2d800 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
2d810 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
2d820 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
2d830 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  e undefined..** 
2d840 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  If [sqlite3_step
2d850 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2d860 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
2d870 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2d880 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66  .** are called f
2d890 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20  rom a different 
2d8a0 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79  thread while any
2d8b0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
2d8c0 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e  es.** are pendin
2d8d0 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  g, then the resu
2d8e0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
2d8f0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
2d900 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2d910 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
2d920 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  rns the.** [SQLI
2d930 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
2d940 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20  atype code] for 
2d950 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61  the initial data
2d960 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20   type.** of the 
2d970 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20  result column.  
2d980 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61  ^The returned va
2d990 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  lue is one of [S
2d9a0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a  QLITE_INTEGER],.
2d9b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ** [SQLITE_FLOAT
2d9c0 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d  ], [SQLITE_TEXT]
2d9d0 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c  , [SQLITE_BLOB],
2d9e0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c   or [SQLITE_NULL
2d9f0 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a  ].  The value.**
2da00 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2da10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2da20 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69  () is only meani
2da30 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65  ngful if no type
2da40 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  .** conversions 
2da50 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73  have occurred as
2da60 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77   described below
2da70 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20  .  After a type 
2da80 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74  conversion,.** t
2da90 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
2daa0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2dab0 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e  umn_type() is un
2dac0 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65  defined.  Future
2dad0 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  .** versions of 
2dae0 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67  SQLite may chang
2daf0 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  e the behavior o
2db00 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  f sqlite3_column
2db10 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f  _type().** follo
2db20 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76  wing a type conv
2db30 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ersion..**.** ^I
2db40 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2db50 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20  a BLOB or UTF-8 
2db60 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
2db70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2db80 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ytes().** routin
2db90 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
2dba0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2dbb0 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
2dbc0 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
2dbd0 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
2dbe0 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  -16 string, then
2dbf0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2dc00 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73  bytes() converts
2dc10 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
2dc20 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e  o UTF-8 and then
2dc30 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2dc40 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
2dc50 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2dc60 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
2dc70 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
2dc80 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75  column_bytes() u
2dc90 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
2dca0 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
2dcb0 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
2dcc0 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72  e to a UTF-8 str
2dcd0 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
2dce0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
2dcf0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
2dd00 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2dd10 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
2dd20 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
2dd30 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65  olumn_bytes() re
2dd40 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
2dd50 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2dd60 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
2dd70 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e  F-16 string then
2dd80 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
2dd90 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a  umn_bytes16().**
2dda0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2ddb0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2ddc0 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
2ddd0 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
2dde0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2ddf0 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  s a UTF-8 string
2de00 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
2de10 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2de20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
2de30 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36  string to UTF-16
2de40 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
2de50 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2de60 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
2de70 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
2de80 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
2de90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2dea0 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a  bytes16() uses.*
2deb0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
2dec0 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
2ded0 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
2dee0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
2def0 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
2df00 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2df10 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
2df20 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
2df30 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
2df40 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2df50 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75  n_bytes16() retu
2df60 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
2df70 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
2df80 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
2df90 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d  _column_bytes()]
2dfa0 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   and .** [sqlite
2dfb0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2dfc0 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75  ()] do not inclu
2dfd0 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  de the zero term
2dfe0 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65  inators at the e
2dff0 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72  nd.** of the str
2e000 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69  ing.  ^For clari
2e010 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72  ty: the values r
2e020 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
2e030 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2e040 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tes()] and [sqli
2e050 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2e060 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75  16()] are the nu
2e070 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73  mber of.** bytes
2e080 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20   in the string, 
2e090 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
2e0a0 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  f characters..**
2e0b0 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74  .** ^Strings ret
2e0c0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2e0d0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61  _column_text() a
2e0e0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2e0f0 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65  n_text16(),.** e
2e100 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67  ven empty string
2e110 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65  s, are always ze
2e120 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
2e130 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76  ^The return.** v
2e140 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
2e150 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
2e160 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74  for a zero-lengt
2e170 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c  h BLOB is a NULL
2e180 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
2e190 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75  ^The object retu
2e1a0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
2e1b0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
2e1c0 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f   is an.** [unpro
2e1d0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2e1e0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41  alue] object.  A
2e1f0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
2e200 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2e210 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ct.** may only b
2e220 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c  e used with [sql
2e230 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
2e240 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2e250 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e  result_value()].
2e260 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72  .** If the [unpr
2e270 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2e280 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65  value] object re
2e290 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
2e2a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
2e2b0 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  ue()] is used in
2e2c0 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20   any other way, 
2e2d0 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a  including calls.
2e2e0 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  ** to routines l
2e2f0 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  ike [sqlite3_val
2e300 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69  ue_int()], [sqli
2e310 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
2e320 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
2e330 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
2e340 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
2e350 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
2e360 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
2e370 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74  utines attempt t
2e380 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
2e390 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70  lue where approp
2e3a0 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20  riate.  ^For.** 
2e3b0 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20  example, if the 
2e3c0 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
2e3d0 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54  ntation is FLOAT
2e3e0 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75   and a text resu
2e3f0 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74  lt.** is request
2e400 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  ed, [sqlite3_snp
2e410 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64  rintf()] is used
2e420 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70   internally to p
2e430 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f  erform the.** co
2e440 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74  nversion automat
2e450 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66  ically.  ^(The f
2e460 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64  ollowing table d
2e470 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65  etails the conve
2e480 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61  rsions.** that a
2e490 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a  re applied:.**.*
2e4a0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  * <blockquote>.*
2e4b0 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
2e4c0 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  "1">.** <tr><th>
2e4d0 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70   Internal<br>Typ
2e4e0 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64  e <th> Requested
2e4f0 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43  <br>Type <th>  C
2e500 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onversion.**.** 
2e510 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2e520 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
2e530 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2e540 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
2e550 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  ULL    <td>  FLO
2e560 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  AT    <td> Resul
2e570 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e  t is 0.0.** <tr>
2e580 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
2e590 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
2e5a0 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55  > Result is a NU
2e5b0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
2e5c0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2e5d0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2e5e0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20  td> Result is a 
2e5f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
2e600 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
2e610 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2e620 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
2e630 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c  om integer to fl
2e640 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
2e650 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
2e660 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
2e670 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
2e680 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  the integer.** <
2e690 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
2e6a0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2e6b0 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54  <td> Same as INT
2e6c0 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  EGER->TEXT.** <t
2e6d0 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
2e6e0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2e6f0 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e  td> [CAST] to IN
2e700 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64  TEGER.** <tr><td
2e710 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
2e720 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
2e730 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
2e740 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c  f the float.** <
2e750 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
2e760 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2e770 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42  <td> [CAST] to B
2e780 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  LOB.** <tr><td> 
2e790 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e   TEXT    <td> IN
2e7a0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41  TEGER   <td> [CA
2e7b0 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a  ST] to INTEGER.*
2e7c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
2e7d0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
2e7e0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
2e7f0 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74  o REAL.** <tr><t
2e800 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
2e810 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2e820 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72  No change.** <tr
2e830 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
2e840 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
2e850 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54  d> [CAST] to INT
2e860 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  EGER.** <tr><td>
2e870 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
2e880 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43  FLOAT    <td> [C
2e890 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20  AST] to REAL.** 
2e8a0 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
2e8b0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
2e8c0 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f   <td> Add a zero
2e8d0 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e   terminator if n
2e8e0 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eeded.** </table
2e8f0 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74  >.** </blockquot
2e900 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  e>)^.**.** The t
2e910 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73  able above makes
2e920 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74   reference to st
2e930 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
2e940 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28   functions atoi(
2e950 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e  ).** and atof().
2e960 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f    SQLite does no
2e970 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65  t really use the
2e980 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49  se functions.  I
2e990 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e  t has its.** own
2e9a0 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65   equivalent inte
2e9b0 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20  rnal routines.  
2e9c0 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61  The atoi() and a
2e9d0 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a  tof() names are.
2e9e0 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74  ** used in the t
2e9f0 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79  able for brevity
2ea00 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65   and because the
2ea10 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74  y are familiar t
2ea20 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67  o most.** C prog
2ea30 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e  rammers..**.** N
2ea40 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79  ote that when ty
2ea50 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f  pe conversions o
2ea60 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72  ccur, pointers r
2ea70 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72  eturned by prior
2ea80 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
2ea90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2eaa0 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  (), sqlite3_colu
2eab0 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f  mn_text(), and/o
2eac0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
2ead0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79  umn_text16() may
2eae0 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e   be invalidated.
2eaf0 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73  .** Type convers
2eb00 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72  ions and pointer
2eb10 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d   invalidations m
2eb20 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ight occur.** in
2eb30 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
2eb40 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ases:.**.** <ul>
2eb50 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
2eb60 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
2eb70 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74  a BLOB and sqlit
2eb80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2eb90 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
2eba0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2ebb0 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
2ebc0 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  A zero-terminato
2ebd0 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20  r might.**      
2ebe0 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64  need to be added
2ebf0 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c   to the string.<
2ec00 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
2ec10 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
2ec20 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61   is UTF-8 text a
2ec30 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2ec40 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a  n_bytes16() or.*
2ec50 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
2ec60 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
2ec70 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
2ec80 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
2ec90 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
2eca0 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e   to UTF-16.</li>
2ecb0 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
2ecc0 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
2ecd0 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20  UTF-16 text and 
2ece0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2ecf0 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20  ytes() or.**    
2ed00 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
2ed10 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65  _text() is calle
2ed20 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
2ed30 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
2ed40 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
2ed50 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  -8.</li>.** </ul
2ed60 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73  >.**.** ^Convers
2ed70 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46  ions between UTF
2ed80 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36  -16be and UTF-16
2ed90 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f  le are always do
2eda0 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20  ne in place and 
2edb0 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69  do.** not invali
2edc0 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69  date a prior poi
2edd0 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20  nter, though of 
2ede0 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65  course the conte
2edf0 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  nt of the buffer
2ee00 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69  .** that the pri
2ee10 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72  or pointer refer
2ee20 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20  ences will have 
2ee30 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20  been modified.  
2ee40 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f  Other kinds.** o
2ee50 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65  f conversion are
2ee60 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77   done in place w
2ee70 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62  hen it is possib
2ee80 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65  le, but sometime
2ee90 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f  s they.** are no
2eea0 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69  t possible and i
2eeb0 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72  n those cases pr
2eec0 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65  ior pointers are
2eed0 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
2eee0 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61  .** The safest a
2eef0 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65  nd easiest to re
2ef00 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73  member policy is
2ef10 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65   to invoke these
2ef20 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20   routines.** in 
2ef30 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
2ef40 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  wing ways:.**.**
2ef50 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71   <ul>.**  <li>sq
2ef60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2ef70 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  t() followed by 
2ef80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2ef90 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
2efa0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
2efb0 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77  mn_blob() follow
2efc0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2efd0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
2efe0 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
2eff0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2f000 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
2f010 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2f020 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c  es16()</li>.** <
2f030 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74  /ul>.**.** In ot
2f040 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73  her words, you s
2f050 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74  hould call sqlit
2f060 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2f070 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ,.** sqlite3_col
2f080 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73  umn_blob(), or s
2f090 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2f0a0 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20  xt16() first to 
2f0b0 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74  force the result
2f0c0 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73  .** into the des
2f0d0 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65  ired format, the
2f0e0 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  n invoke sqlite3
2f0f0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2f100 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
2f110 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74  lumn_bytes16() t
2f120 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20  o find the size 
2f130 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20  of the result.  
2f140 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  Do not mix calls
2f150 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  .** to sqlite3_c
2f160 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20  olumn_text() or 
2f170 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2f180 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73  lob() with calls
2f190 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
2f1a0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c  olumn_bytes16(),
2f1b0 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20   and do not mix 
2f1c0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2f1d0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2f1e0 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74  .** with calls t
2f1f0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2f200 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20  _bytes()..**.** 
2f210 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65  ^The pointers re
2f220 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64  turned are valid
2f230 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f   until a type co
2f240 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20  nversion occurs 
2f250 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20  as.** described 
2f260 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20  above, or until 
2f270 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f280 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
2f290 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
2f2a0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2f2b0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68   is called.  ^Th
2f2c0 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75  e memory space u
2f2d0 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69  sed to hold stri
2f2e0 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73  ngs.** and BLOBs
2f2f0 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61   is freed automa
2f300 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e  tically.  Do <b>
2f310 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65  not</b> pass the
2f320 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
2f330 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
2f340 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2f350 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  )], [sqlite3_col
2f360 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63  umn_text()], etc
2f370 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  . into.** [sqlit
2f380 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a  e3_free()]..**.*
2f390 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20  * ^(If a memory 
2f3a0 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
2f3b0 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
2f3c0 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  he evaluation of
2f3d0 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65   any.** of these
2f3e0 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66   routines, a def
2f3f0 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65  ault value is re
2f400 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66  turned.  The def
2f410 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73  ault value.** is
2f420 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65   either the inte
2f430 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74  ger 0, the float
2f440 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
2f450 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a   0.0, or a NULL.
2f460 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62  ** pointer.  Sub
2f470 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
2f480 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
2f490 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  e()] will return
2f4a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
2f4b0 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  M].)^.*/.const v
2f4c0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2f4d0 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  umn_blob(sqlite3
2f4e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2f4f0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2f500 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69  olumn_bytes(sqli
2f510 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2f520 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
2f530 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2f540 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2f550 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c  int iCol);.doubl
2f560 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2f570 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
2f580 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2f590 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
2f5a0 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33  lumn_int(sqlite3
2f5b0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2f5c0 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
2f5d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f5e0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
2f5f0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2f600 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
2f610 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2f620 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33  umn_text(sqlite3
2f630 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2f640 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2f650 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2f660 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
2f670 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
2f680 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2f690 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  n_type(sqlite3_s
2f6a0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2f6b0 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a  .sqlite3_value *
2f6c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2f6d0 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
2f6e0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a  t*, int iCol);..
2f6f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2f700 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72  Destroy A Prepar
2f710 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
2f720 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ect.**.** ^The s
2f730 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2f740 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
2f750 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61  lled to delete a
2f760 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2f770 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  ment]..** ^If th
2f780 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
2f790 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  aluation of the 
2f7a0 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e  statement encoun
2f7b0 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a  tered no errors.
2f7c0 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61  ** or if the sta
2f7d0 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20  tement is never 
2f7e0 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20  been evaluated, 
2f7f0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e  then sqlite3_fin
2f800 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a  alize() returns.
2f810 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e  ** SQLITE_OK.  ^
2f820 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
2f830 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
2f840 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69   statement S fai
2f850 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  led, then.** sql
2f860 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
2f870 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70   returns the app
2f880 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
2f890 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
2f8a0 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
2f8b0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
2f8c0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
2f8d0 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  ) routine can be
2f8e0 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70   called at any p
2f8f0 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74  oint during.** t
2f900 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66  he life cycle of
2f910 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2f920 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f  ment] S:.** befo
2f930 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69  re statement S i
2f940 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64  s ever evaluated
2f950 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f  , after.** one o
2f960 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20  r more calls to 
2f970 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2f980 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20  ], or after any 
2f990 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  call.** to [sqli
2f9a0 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61  te3_step()] rega
2f9b0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
2f9c0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61  r or not the sta
2f9d0 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f  tement has.** co
2f9e0 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f  mpleted executio
2f9f0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69  n..**.** ^Invoki
2fa00 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  ng sqlite3_final
2fa10 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20  ize() on a NULL 
2fa20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72  pointer is a har
2fa30 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a  mless no-op..**.
2fa40 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
2fa50 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65  on must finalize
2fa60 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64   every [prepared
2fa70 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f   statement] in o
2fa80 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  rder to avoid.**
2fa90 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e   resource leaks.
2faa0 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f    It is a grievo
2fab0 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65  us error for the
2fac0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
2fad0 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20  try to use.** a 
2fae0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2faf0 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
2fb00 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20  been finalized. 
2fb10 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72   Any use of a pr
2fb20 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
2fb30 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73  ent after it has
2fb40 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20   been finalized 
2fb50 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  can result in un
2fb60 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75  defined and.** u
2fb70 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76  ndesirable behav
2fb80 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66  ior such as segf
2fb90 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63  aults and heap c
2fba0 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e  orruption..*/.in
2fbb0 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  t sqlite3_finali
2fbc0 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ze(sqlite3_stmt 
2fbd0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2fbe0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
2fbf0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2fc00 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
2fc10 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
2fc20 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
2fc30 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
2fc40 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  t a [prepared st
2fc50 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
2fc60 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ct back to its i
2fc70 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
2fc80 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
2fc90 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53  cuted..** ^Any S
2fca0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
2fcb0 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
2fcc0 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
2fcd0 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68  them using.** th
2fce0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
2fcf0 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
2fd00 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74  ind_*() API] ret
2fd10 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73  ain their values
2fd20 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65  ..** Use [sqlite
2fd30 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
2fd40 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
2fd50 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a   bindings..**.**
2fd60 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
2fd70 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
2fd80 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70  ce resets the [p
2fd90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2fda0 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20  t] S.** back to 
2fdb0 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
2fdc0 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a   its program..**
2fdd0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
2fde0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
2fdf0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2fe00 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
2fe10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2fe20 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51  ] S returned [SQ
2fe30 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51  LITE_ROW] or [SQ
2fe40 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f  LITE_DONE],.** o
2fe50 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  r if [sqlite3_st
2fe60 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72  ep(S)] has never
2fe70 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c   before been cal
2fe80 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65  led on S,.** the
2fe90 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
2fea0 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  (S)] returns [SQ
2feb0 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
2fec0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
2fed0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
2fee0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
2fef0 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
2ff00 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2ff10 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72  indicated an err
2ff20 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c  or, then.** [sql
2ff30 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
2ff40 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70  eturns an approp
2ff50 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
2ff60 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  e]..**.** ^The [
2ff70 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2ff80 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
2ff90 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
2ffa0 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79  values.** of any
2ffb0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2ffc0 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  lob|bindings] on
2ffd0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2ffe0 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
2fff0 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65  int sqlite3_rese
30000 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
30010 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
30020 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
30030 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
30040 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  Functions.** KEY
30050 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e  WORDS: {function
30060 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
30070 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
30080 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
30090 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
300a0 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  on}.** KEYWORDS:
300b0 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
300c0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
300d0 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ons}.**.** ^Thes
300e0 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c  e functions (col
300f0 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20  lectively known 
30100 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65  as "function cre
30110 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29  ation routines")
30120 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20  .** are used to 
30130 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
30140 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20  s or aggregates 
30150 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74  or to redefine t
30160 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
30170 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing SQL f
30180 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
30190 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c  egates.  The onl
301a0 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65  y differences be
301b0 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72  tween.** these r
301c0 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20  outines are the 
301d0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78  text encoding ex
301e0 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68  pected for.** th
301f0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
30200 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20  er (the name of 
30210 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69  the function bei
30220 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61  ng created).** a
30230 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  nd the presence 
30240 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20  or absence of a 
30250 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
30260 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ack for.** the a
30270 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
30280 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
30290 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
302a0 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61  ter is the [data
302b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
302c0 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51   to which the SQ
302d0 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  L.** function is
302e0 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e   to be added.  ^
302f0 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  If an applicatio
30300 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e  n uses more than
30310 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   one database.**
30320 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e   connection then
30330 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
30340 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
30350 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64  ns must be added
30360 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61  .** to each data
30370 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
30380 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
30390 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  * ^The second pa
303a0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
303b0 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ame of the SQL f
303c0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72  unction to be cr
303d0 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65  eated or.** rede
303e0 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e  fined.  ^The len
303f0 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20  gth of the name 
30400 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35  is limited to 25
30410 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46  5 bytes in a UTF
30420 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61  -8.** representa
30430 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20  tion, exclusive 
30440 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  of the zero-term
30450 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74  inator.  ^Note t
30460 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20  hat the name.** 
30470 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20  length limit is 
30480 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20  in UTF-8 bytes, 
30490 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e  not characters n
304a0 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e  or UTF-16 bytes.
304b0 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d    .** ^Any attem
304c0 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66  pt to create a f
304d0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c  unction with a l
304e0 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69  onger name.** wi
304f0 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51  ll result in [SQ
30500 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69  LITE_MISUSE] bei
30510 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  ng returned..**.
30520 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  ** ^The third pa
30530 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a  rameter (nArg).*
30540 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  * is the number 
30550 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  of arguments tha
30560 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
30570 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
30580 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68  te takes. ^If th
30590 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  is parameter is 
305a0 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c  -1, then the SQL
305b0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
305c0 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61  aggregate may ta
305d0 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ke any number of
305e0 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65   arguments betwe
305f0 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d  en 0 and the lim
30600 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71  it.** set by [sq
30610 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
30620 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
30630 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74  ION_ARG]).  If t
30640 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
30650 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68  meter is less th
30660 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72  an -1 or greater
30670 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74   than 127 then t
30680 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a  he behavior is.*
30690 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
306a0 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
306b0 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
306c0 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
306d0 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  at.** [SQLITE_UT
306e0 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69  F8 | text encodi
306f0 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e  ng] this SQL fun
30700 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f  ction prefers fo
30710 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74  r.** its paramet
30720 65 72 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63  ers.  The applic
30730 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74  ation should set
30740 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
30750 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  to.** [SQLITE_UT
30760 46 31 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75  F16LE] if the fu
30770 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
30780 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a  ation invokes .*
30790 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
307a0 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20  _text16le()] on 
307b0 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51  an input, or [SQ
307c0 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66  LITE_UTF16BE] if
307d0 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
307e0 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b  tation invokes [
307f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
30800 78 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20  xt16be()] on an 
30810 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51  input, or.** [SQ
30820 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b  LITE_UTF16] if [
30830 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
30840 78 74 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  xt16()] is used,
30850 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38   or [SQLITE_UTF8
30860 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20  ].** otherwise. 
30870 20 5e 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66   ^The same SQL f
30880 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
30890 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70  egistered multip
308a0 6c 65 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a  le times using.*
308b0 2a 20 64 69 66 66 65 72 65 6e 74 20 70 72 65 66  * different pref
308c0 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
308d0 69 6e 67 73 2c 20 77 69 74 68 20 64 69 66 66 65  ings, with diffe
308e0 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
308f0 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ions for.** each
30900 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57   encoding..** ^W
30910 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  hen multiple imp
30920 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
30930 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
30940 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c  n are available,
30950 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
30960 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61  pick the one tha
30970 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c  t involves the l
30980 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64  east amount of d
30990 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ata conversion..
309a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
309b0 68 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  h parameter may 
309c0 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52  optionally be OR
309d0 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
309e0 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a  DETERMINISTIC].*
309f0 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74  * to signal that
30a00 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69   the function wi
30a10 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  ll always return
30a20 20 74 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74   the same result
30a30 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61   given.** the sa
30a40 6d 65 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e  me inputs within
30a50 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74   a single SQL st
30a60 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53  atement.  Most S
30a70 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  QL functions are
30a80 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69  .** deterministi
30a90 63 2e 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e  c.  The built-in
30aa0 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20   [random()] SQL 
30ab0 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65  function is an e
30ac0 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66  xample of a.** f
30ad0 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20  unction that is 
30ae0 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69  not deterministi
30af0 63 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 71  c.  The SQLite q
30b00 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20  uery planner is 
30b10 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f  able to.** perfo
30b20 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70  rm additional op
30b30 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64  timizations on d
30b40 65 74 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e  eterministic fun
30b50 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a  ctions, so use.*
30b60 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  * of the [SQLITE
30b70 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20  _DETERMINISTIC] 
30b80 66 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e  flag is recommen
30b90 64 65 64 20 77 68 65 72 65 20 70 6f 73 73 69 62  ded where possib
30ba0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  le..**.** ^(The 
30bb0 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
30bc0 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
30bd0 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d  pointer.  The im
30be0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
30bf0 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
30c00 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20  can gain access 
30c10 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20  to this pointer 
30c20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75  using [sqlite3_u
30c30 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a  ser_data()].)^.*
30c40 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c  *.** ^The sixth,
30c50 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67   seventh and eig
30c60 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20  hth parameters, 
30c70 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64  xFunc, xStep and
30c80 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20   xFinal, are.** 
30c90 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61  pointers to C-la
30ca0 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73  nguage functions
30cb0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
30cc0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
30cd0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
30ce0 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20  . ^A scalar SQL 
30cf0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
30d00 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
30d10 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63  ion of the xFunc
30d20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c  .** callback onl
30d30 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  y; NULL pointers
30d40 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
30d50 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64  as the xStep and
30d60 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d   xFinal.** param
30d70 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65  eters. ^An aggre
30d80 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
30d90 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
30da0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
30db0 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69  xStep.** and xFi
30dc0 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69  nal and NULL poi
30dd0 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73  nter must be pas
30de0 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e  sed for xFunc. ^
30df0 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69  To delete an exi
30e00 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e  sting.** SQL fun
30e10 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
30e20 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f  te, pass NULL po
30e30 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74  inters for all t
30e40 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  hree function.**
30e50 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a   callbacks..**.*
30e60 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68  * ^(If the ninth
30e70 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
30e80 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
30e90 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f  ction_v2() is no
30ea0 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20  t NULL,.** then 
30eb0 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72  it is destructor
30ec0 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
30ed0 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
30ee0 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72  r. .** The destr
30ef0 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64  uctor is invoked
30f00 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   when the functi
30f10 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65  on is deleted, e
30f20 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a  ither by being.*
30f30 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20  * overloaded or 
30f40 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
30f50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
30f60 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64  ses.)^.** ^The d
30f70 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73  estructor is als
30f80 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65  o invoked if the
30f90 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
30fa0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
30fb0 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a  ion_v2() fails..
30fc0 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73  ** ^When the des
30fd0 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
30fe0 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61   of the tenth pa
30ff0 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b  rameter is invok
31000 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73  ed, it.** is pas
31010 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67  sed a single arg
31020 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
31030 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70   copy of the app
31040 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a  lication data .*
31050 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20  * pointer which 
31060 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61  was the fifth pa
31070 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
31080 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
31090 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  on_v2()..**.** ^
310a0 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  It is permitted 
310b0 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74  to register mult
310c0 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
310d0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
310e0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69  .** functions wi
310f0 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  th the same name
31100 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72   but with either
31110 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65   differing numbe
31120 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e  rs of.** argumen
31130 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20  ts or differing 
31140 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
31150 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69  ncodings.  ^SQLi
31160 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74  te will use.** t
31170 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
31180 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73  n that most clos
31190 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20  ely matches the 
311a0 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65  way in which the
311b0 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
311c0 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75   is used.  ^A fu
311d0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
311e0 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e  ation with a non
311f0 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72  -negative.** nAr
31200 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  g parameter is a
31210 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68   better match th
31220 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d  an a function im
31230 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
31240 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20  h.** a negative 
31250 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69  nArg.  ^A functi
31260 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65  on where the pre
31270 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
31280 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20  ding.** matches 
31290 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63  the database enc
312a0 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65  oding is a bette
312b0 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20  r.** match than 
312c0 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
312d0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73   the encoding is
312e0 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a   different.  .**
312f0 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
31300 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
31310 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65  difference is be
31320 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e  tween UTF16le an
31330 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20  d UTF16be.** is 
31340 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74  a closer match t
31350 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
31360 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
31370 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a  g difference is.
31380 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20  ** between UTF8 
31390 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a  and UTF16..**.**
313a0 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74   ^Built-in funct
313b0 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72  ions may be over
313c0 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70  loaded by new ap
313d0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
313e0 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  d functions..**.
313f0 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69  ** ^An applicati
31400 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
31410 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
31420 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a   to call other.*
31430 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
31440 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73  ces.  However, s
31450 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e  uch calls must n
31460 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20  ot.** close the 
31470 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
31480 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65  ion nor finalize
31490 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72   or reset the pr
314a0 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
314b0 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65  ent in which the
314c0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
314d0 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ning..*/.int sql
314e0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
314f0 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20  tion(.  sqlite3 
31500 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
31510 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
31520 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
31530 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
31540 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
31550 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
31560 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
31570 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
31580 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
31590 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
315a0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
315b0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
315c0 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
315d0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
315e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
315f0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20  te_function16(. 
31600 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
31610 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e  const void *zFun
31620 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
31630 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
31640 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
31650 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
31660 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
31670 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
31680 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
31690 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
316a0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
316b0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
316c0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
316d0 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
316e0 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  ext*).);.int sql
316f0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
31700 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74  tion_v2(.  sqlit
31710 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
31720 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
31730 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
31740 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
31750 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
31760 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
31770 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
31780 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
31790 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
317a0 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
317b0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
317c0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
317d0 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
317e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c  lite3_context*),
317f0 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
31800 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  y)(void*).);../*
31810 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
31820 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a  xt Encodings.**.
31830 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
31840 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72  t define integer
31850 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72   codes that repr
31860 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75  esent the variou
31870 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69  s.** text encodi
31880 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79  ngs supported by
31890 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
318a0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20  ine SQLITE_UTF8 
318b0 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
318c0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
318d0 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  LE        2.#def
318e0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
318f0 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66  BE        3.#def
31900 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
31910 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f            4    /
31920 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74  * Use native byt
31930 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69  e order */.#defi
31940 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20  ne SQLITE_ANY   
31950 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a           5    /*
31960 20 44 65 70 72 65 63 61 74 65 64 20 2a 2f 0a 23   Deprecated */.#
31970 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
31980 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20  F16_ALIGNED  8  
31990 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
319a0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e  ate_collation on
319b0 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ly */../*.** CAP
319c0 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20  I3REF: Function 
319d0 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  Flags.**.** Thes
319e0 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20  e constants may 
319f0 62 65 20 4f 52 65 64 20 74 6f 67 65 74 68 65 72  be ORed together
31a00 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53   with the .** [S
31a10 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 70 72 65  QLITE_UTF8 | pre
31a20 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
31a30 64 69 6e 67 5d 20 61 73 20 74 68 65 20 66 6f 75  ding] as the fou
31a40 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rth argument.** 
31a50 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
31a60 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20  te_function()], 
31a70 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
31a80 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f  function16()], o
31a90 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  r.** [sqlite3_cr
31aa0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
31ab0 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ()]..*/.#define 
31ac0 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49  SQLITE_DETERMINI
31ad0 53 54 49 43 20 20 20 20 30 78 38 30 30 0a 0a 2f  STIC    0x800../
31ae0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
31af0 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69  eprecated Functi
31b00 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45  ons.** DEPRECATE
31b10 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  D.**.** These fu
31b20 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70  nctions are [dep
31b30 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72  recated].  In or
31b40 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a  der to maintain.
31b50 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
31b60 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20  patibility with 
31b70 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73  older code, thes
31b80 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74  e functions cont
31b90 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73  inue .** to be s
31ba0 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76  upported.  Howev
31bb0 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74  er, new applicat
31bc0 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69  ions should avoi
31bd0 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20  d.** the use of 
31be0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
31bf0 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72    To help encour
31c00 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76  age people to av
31c10 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65  oid.** using the
31c20 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65  se functions, we
31c30 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74   are not going t
31c40 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20  o tell you what 
31c50 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e  they do..*/.#ifn
31c60 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
31c70 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54  DEPRECATED.SQLIT
31c80 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
31c90 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
31ca0 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  te_count(sqlite3
31cb0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49  _context*);.SQLI
31cc0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
31cd0 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65  t sqlite3_expire
31ce0 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  d(sqlite3_stmt*)
31cf0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
31d00 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
31d10 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67  transfer_binding
31d20 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
31d30 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b   sqlite3_stmt*);
31d40 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
31d50 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  ED int sqlite3_g
31d60 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f  lobal_recover(vo
31d70 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  id);.SQLITE_DEPR
31d80 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69  ECATED void sqli
31d90 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e  te3_thread_clean
31da0 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  up(void);.SQLITE
31db0 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
31dc0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61  sqlite3_memory_a
31dd0 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69  larm(void(*)(voi
31de0 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
31df0 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20 20 20 20  ,int),.         
31e00 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
31e10 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
31e20 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
31e30 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
31e40 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f  ning SQL Functio
31e50 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75  n Parameter Valu
31e60 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c  es.**.** The C-l
31e70 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e  anguage implemen
31e80 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75  tation of SQL fu
31e90 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
31ea0 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74  egates uses.** t
31eb0 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72  his set of inter
31ec0 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  face routines to
31ed0 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61   access the para
31ee0 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a  meter values on.
31ef0 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ** the function 
31f00 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a  or aggregate..**
31f10 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66  .** The xFunc (f
31f20 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69  or scalar functi
31f30 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66  ons) or xStep (f
31f40 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70  or aggregates) p
31f50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
31f60 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
31f70 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
31f80 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
31f90 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
31fa0 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b   define callback
31fb0 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
31fc0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
31fd0 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
31fe0 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61  s..** The 3rd pa
31ff0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65  rameter to these
32000 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e   callbacks is an
32010 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
32020 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63  rs to.** [protec
32030 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
32040 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65  e] objects.  The
32050 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74  re is one [sqlit
32060 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
32070 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72   for.** each par
32080 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51  ameter to the SQ
32090 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65  L function.  The
320a0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
320b0 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61  used to.** extra
320c0 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74  ct values from t
320d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
320e0 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a  e] objects..**.*
320f0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
32100 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20   work only with 
32110 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
32120 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
32130 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  s..** Any attemp
32140 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72  t to use these r
32150 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75  outines on an [u
32160 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
32170 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a  e3_value].** obj
32180 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75  ect results in u
32190 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
321a0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  r..**.** ^These 
321b0 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75  routines work ju
321c0 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72  st like the corr
321d0 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d  esponding [colum
321e0 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
321f0 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  ns].** except th
32200 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e  at  these routin
32210 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65  es take a single
32220 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
32230 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
32240 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73  t.** pointer ins
32250 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74  tead of a [sqlit
32260 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65  e3_stmt*] pointe
32270 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72  r and an integer
32280 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a   column number..
32290 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
322a0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
322b0 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72  ) interface extr
322c0 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74  acts a UTF-16 st
322d0 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  ring.** in the n
322e0 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72  ative byte-order
322f0 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63   of the host mac
32300 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  hine.  ^The.** s
32310 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
32320 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69  t16be() and sqli
32330 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
32340 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  le() interfaces.
32350 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31  ** extract UTF-1
32360 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67  6 strings as big
32370 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74  -endian and litt
32380 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63  le-endian respec
32390 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28  tively..**.** ^(
323a0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
323b0 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29  e_numeric_type()
323c0 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
323d0 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20  pts to apply.** 
323e0 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79  numeric affinity
323f0 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20   to the value.  
32400 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20  This means that 
32410 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a  an attempt is.**
32420 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74   made to convert
32430 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e   the value to an
32440 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61   integer or floa
32450 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a  ting point.  If.
32460 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72  ** such a conver
32470 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65  sion is possible
32480 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66   without loss of
32490 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e   information (in
324a0 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c   other.** words,
324b0 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73   if the value is
324c0 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c   a string that l
324d0 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62  ooks like a numb
324e0 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  er).** then the 
324f0 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65  conversion is pe
32500 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77  rformed.  Otherw
32510 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f  ise no conversio
32520 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65  n occurs..** The
32530 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
32540 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74   | datatype] aft
32550 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  er conversion is
32560 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a   returned.)^.**.
32570 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61  ** Please pay pa
32580 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69  rticular attenti
32590 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74  on to the fact t
325a0 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20  hat the pointer 
325b0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d  returned.** from
325c0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
325d0 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
325e0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
325f0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
32600 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20  value_text16()] 
32610 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74  can be invalidat
32620 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65  ed by a subseque
32630 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
32640 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
32650 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  es()], [sqlite3_
32660 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d  value_bytes16()]
32670 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
32680 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
32690 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
326a0 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  ext16()]..**.** 
326b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
326c0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
326d0 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
326e0 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c  ad as.** the SQL
326f0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73   function that s
32700 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c  upplied the [sql
32710 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72  ite3_value*] par
32720 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73  ameters..*/.cons
32730 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
32740 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74  value_blob(sqlit
32750 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
32760 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
32770 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  tes(sqlite3_valu
32780 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
32790 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73  _value_bytes16(s
327a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
327b0 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76  double sqlite3_v
327c0 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69  alue_double(sqli
327d0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
327e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
327f0 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt(sqlite3_value
32800 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  *);.sqlite3_int6
32810 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  4 sqlite3_value_
32820 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61  int64(sqlite3_va
32830 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  lue*);.const uns
32840 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
32850 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73  te3_value_text(s
32860 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
32870 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
32880 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
32890 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
328a0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
328b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
328c0 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16le(sqlite3_val
328d0 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
328e0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
328f0 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
32900 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
32910 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
32920 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
32930 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
32940 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
32950 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
32960 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
32970 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67  F: Obtain Aggreg
32980 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  ate Function Con
32990 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65  text.**.** Imple
329a0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67  mentations of ag
329b0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
329c0 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a  tions use this.*
329d0 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c  * routine to all
329e0 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72  ocate memory for
329f0 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73   storing their s
32a00 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tate..**.** ^The
32a10 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20   first time the 
32a20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
32a30 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72  e_context(C,N) r
32a40 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64  outine is called
32a50 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69   .** for a parti
32a60 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 20  cular aggregate 
32a70 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65  function, SQLite
32a80 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20  .** allocates N 
32a90 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65  of memory, zeroe
32aa0 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72  s out that memor
32ab0 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  y, and returns a
32ac0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
32ad0 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e  he new memory. ^
32ae0 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  On second and su
32af0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
32b00 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67  o.** sqlite3_agg
32b10 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
32b20 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67   for the same ag
32b30 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
32b40 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68   instance,.** th
32b50 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73  e same buffer is
32b60 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69   returned.  Sqli
32b70 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
32b80 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61  ntext() is norma
32b90 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e  lly.** called on
32ba0 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f  ce for each invo
32bb0 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53  cation of the xS
32bc0 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64  tep callback and
32bd0 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73   then one.** las
32be0 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20  t time when the 
32bf0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20  xFinal callback 
32c00 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57  is invoked.  ^(W
32c10 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63  hen no rows matc
32c20 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74  h.** an aggregat
32c30 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 74  e query, the xSt
32c40 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66  ep() callback of
32c50 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66   the aggregate f
32c60 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65  unction.** imple
32c70 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76  mentation is nev
32c80 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46  er called and xF
32c90 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64  inal() is called
32ca0 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a   exactly once..*
32cb0 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73  * In those cases
32cc0 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  , sqlite3_aggreg
32cd0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69  ate_context() mi
32ce0 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f  ght be called fo
32cf0 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  r the.** first t
32d00 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20  ime from within 
32d10 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a  xFinal().)^.**.*
32d20 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61  * ^The sqlite3_a
32d30 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
32d40 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65  (C,N) routine re
32d50 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
32d60 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69  nter .** when fi
32d70 72 73 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20  rst called if N 
32d80 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  is less than or 
32d90 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72  equal to zero or
32da0 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20   if a memory.** 
32db0 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f  allocate error o
32dc0 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ccurs..**.** ^(T
32dd0 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61  he amount of spa
32de0 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ce allocated by 
32df0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
32e00 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69  e_context(C,N) i
32e10 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20  s.** determined 
32e20 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74  by the N paramet
32e30 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63  er on first succ
32e40 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68  essful call.  Ch
32e50 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61  anging the.** va
32e60 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73  lue of N in subs
32e70 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73  equent call to s
32e80 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
32e90 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69  _context() withi
32ea0 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67  n.** the same ag
32eb0 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
32ec0 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e   instance will n
32ed0 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65  ot resize the me
32ee0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
32ef0 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68  on.)^  Within th
32f00 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  e xFinal callbac
32f10 6b 2c 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61  k, it is customa
32f20 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30  ry to set.** N=0
32f30 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c   in calls to sql
32f40 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
32f50 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74  ontext(C,N) so t
32f60 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74  hat no .** point
32f70 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  less memory allo
32f80 63 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a  cations occur..*
32f90 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74  *.** ^SQLite aut
32fa0 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73  omatically frees
32fb0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
32fc0 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c  cated by .** sql
32fd0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
32fe0 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68  ontext() when th
32ff0 65 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72  e aggregate quer
33000 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a  y concludes..**.
33010 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
33020 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61  ameter must be a
33030 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
33040 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
33050 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20   | SQL function 
33060 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73  context] that is
33070 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
33080 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78  eter.** to the x
33090 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63  Step or xFinal c
330a0 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
330b0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
330c0 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a  the aggregate.**
330d0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
330e0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
330f0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
33100 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
33110 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
33120 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  e aggregate SQL 
33130 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
33140 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
33150 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
33160 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f  context(sqlite3_
33170 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42  context*, int nB
33180 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ytes);../*.** CA
33190 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74  PI3REF: User Dat
331a0 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a  a For Functions.
331b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
331c0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69  e3_user_data() i
331d0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
331e0 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
331f0 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77  e pointer that w
33200 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61  as the pUserData
33210 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
33220 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  5th parameter).*
33230 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
33240 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
33250 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
33260 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
33270 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
33280 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
33290 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
332a0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
332b0 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
332c0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
332d0 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
332e0 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
332f0 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
33300 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  ch.** the applic
33310 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
33320 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
33330 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
33340 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71  te3_user_data(sq
33350 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
33360 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33370 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
33380 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69  ction For Functi
33390 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ons.**.** ^The s
333a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
333b0 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72  b_handle() inter
333c0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
333d0 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
333e0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61  inter to the [da
333f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
33400 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61  n] (the 1st para
33410 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
33420 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
33430 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
33440 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
33450 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
33460 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
33470 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
33480 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
33490 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
334a0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71   function..*/.sq
334b0 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63  lite3 *sqlite3_c
334c0 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
334d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
334e0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
334f0 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75  REF: Function Au
33500 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a  xiliary Data.**.
33510 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
33520 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62  ns may be used b
33530 79 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65  y (non-aggregate
33540 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  ) SQL functions 
33550 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20  to.** associate 
33560 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72  metadata with ar
33570 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49  gument values. I
33580 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  f the same value
33590 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a   is passed to.**
335a0 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61   multiple invoca
335b0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
335c0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64  e SQL function d
335d0 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63  uring query exec
335e0 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20  ution, under.** 
335f0 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63  some circumstanc
33600 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65  es the associate
33610 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62  d metadata may b
33620 65 20 70 72 65 73 65 72 76 65 64 2e 20 20 41 6e  e preserved.  An
33630 20 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77   example.** of w
33640 68 65 72 65 20 74 68 69 73 20 6d 69 67 68 74 20  here this might 
33650 62 65 20 75 73 65 66 75 6c 20 69 73 20 69 6e 20  be useful is in 
33660 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73  a regular-expres
33670 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a 2a 2a  sion matching.**
33680 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63   function. The c
33690 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20  ompiled version 
336a0 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  of the regular e
336b0 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65  xpression can be
336c0 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65   stored as.** me
336d0 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65  tadata associate
336e0 64 20 77 69 74 68 20 74 68 65 20 70 61 74 74 65  d with the patte
336f0 72 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a 2a 20  rn string.  .** 
33700 54 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61 73 20  Then as long as 
33710 74 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69  the pattern stri
33720 6e 67 20 72 65 6d 61 69 6e 73 20 74 68 65 20 73  ng remains the s
33730 61 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d 70  ame,.** the comp
33740 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70  iled regular exp
33750 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72  ression can be r
33760 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c  eused on multipl
33770 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  e.** invocations
33780 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
33790 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ction..**.** ^Th
337a0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
337b0 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
337c0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
337d0 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64  ter to the metad
337e0 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
337f0 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
33800 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66  _set_auxdata() f
33810 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65  unction with the
33820 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   Nth argument.**
33830 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70   value to the ap
33840 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
33850 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20  d function. ^If 
33860 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61  there is no meta
33870 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74  data.** associat
33880 65 64 20 77 69 74 68 20 74 68 65 20 66 75 6e 63  ed with the func
33890 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c 20 74  tion argument, t
338a0 68 69 73 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  his sqlite3_get_
338b0 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
338c0 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  ace.** returns a
338d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
338e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
338f0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
33900 4e 2c 50 2c 58 29 20 69 6e 74 65 72 66 61 63 65  N,P,X) interface
33910 20 73 61 76 65 73 20 50 20 61 73 20 6d 65 74 61   saves P as meta
33920 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74  data for the N-t
33930 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66  h.** argument of
33940 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
33950 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
33960 6e 2e 20 20 5e 53 75 62 73 65 71 75 65 6e 74 0a  n.  ^Subsequent.
33970 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
33980 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
33990 43 2c 4e 29 20 72 65 74 75 72 6e 20 50 20 66 72  C,N) return P fr
339a0 6f 6d 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  om the most rece
339b0 6e 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65  nt.** sqlite3_se
339c0 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
339d0 58 29 20 63 61 6c 6c 20 69 66 20 74 68 65 20 6d  X) call if the m
339e0 65 74 61 64 61 74 61 20 69 73 20 73 74 69 6c 6c  etadata is still
339f0 20 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c   valid or.** NUL
33a00 4c 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 74  L if the metadat
33a10 61 20 68 61 73 20 62 65 65 6e 20 64 69 73 63 61  a has been disca
33a20 72 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65 72 20  rded..** ^After 
33a30 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c  each call to sql
33a40 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
33a50 28 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72 65 20  (C,N,P,X) where 
33a60 58 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a  X is not NULL,.*
33a70 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e  * SQLite will in
33a80 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63  voke the destruc
33a90 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58 20 77  tor function X w
33aa0 69 74 68 20 70 61 72 61 6d 65 74 65 72 20 50 20  ith parameter P 
33ab0 65 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c  exactly.** once,
33ac0 20 77 68 65 6e 20 74 68 65 20 6d 65 74 61 64 61   when the metada
33ad0 74 61 20 69 73 20 64 69 73 63 61 72 64 65 64 2e  ta is discarded.
33ae0 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72  .** SQLite is fr
33af0 65 65 20 74 6f 20 64 69 73 63 61 72 64 20 74 68  ee to discard th
33b00 65 20 6d 65 74 61 64 61 74 61 20 61 74 20 61 6e  e metadata at an
33b10 79 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64 69 6e  y time, includin
33b20 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  g: <ul>.** <li> 
33b30 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70  when the corresp
33b40 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  onding function 
33b50 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65  parameter change
33b60 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68  s, or.** <li> wh
33b70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  en [sqlite3_rese
33b80 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
33b90 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20  _finalize()] is 
33ba0 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a  called for the.*
33bb0 2a 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 65  *      SQL state
33bc0 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ment, or.** <li>
33bd0 20 77 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 65   when sqlite3_se
33be0 74 5f 61 75 78 64 61 74 61 28 29 20 69 73 20 69  t_auxdata() is i
33bf0 6e 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f 6e 20  nvoked again on 
33c00 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74  the same paramet
33c10 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64  er, or.** <li> d
33c20 75 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e  uring the origin
33c30 61 6c 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  al sqlite3_set_a
33c40 75 78 64 61 74 61 28 29 20 63 61 6c 6c 20 77 68  uxdata() call wh
33c50 65 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20  en a memory .** 
33c60 20 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20       allocation 
33c70 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 3c 2f  error occurs. </
33c80 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  ul>)^.**.** Note
33c90 20 74 68 65 20 6c 61 73 74 20 62 75 6c 6c 65 74   the last bullet
33ca0 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 2e 20   in particular. 
33cb0 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   The destructor 
33cc0 58 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74 65 33  X in .** sqlite3
33cd0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _set_auxdata(C,N
33ce0 2c 50 2c 58 29 20 6d 69 67 68 74 20 62 65 20 63  ,P,X) might be c
33cf0 61 6c 6c 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  alled immediatel
33d00 79 2c 20 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a  y, before the.**
33d10 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
33d20 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
33d30 20 65 76 65 6e 20 72 65 74 75 72 6e 73 2e 20 20   even returns.  
33d40 48 65 6e 63 65 20 73 71 6c 69 74 65 33 5f 73 65  Hence sqlite3_se
33d50 74 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a 20 73  t_auxdata().** s
33d60 68 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65 64 20  hould be called 
33d70 6e 65 61 72 20 74 68 65 20 65 6e 64 20 6f 66 20  near the end of 
33d80 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  the function imp
33d90 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 20  lementation and 
33da0 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
33db0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
33dc0 68 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b 65 20 61  hould not make a
33dd0 6e 79 20 75 73 65 20 6f 66 20 50 20 61 66 74 65  ny use of P afte
33de0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74  r.** sqlite3_set
33df0 5f 61 75 78 64 61 74 61 28 29 20 68 61 73 20 62  _auxdata() has b
33e00 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a  een called..**.*
33e10 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c  * ^(In practice,
33e20 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65   metadata is pre
33e30 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66  served between f
33e40 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f  unction calls fo
33e50 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61  r.** function pa
33e60 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72  rameters that ar
33e70 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63  e compile-time c
33e80 6f 6e 73 74 61 6e 74 73 2c 20 69 6e 63 6c 75 64  onstants, includ
33e90 69 6e 67 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76  ing literal.** v
33ea0 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d  alues and [param
33eb0 65 74 65 72 73 5d 20 61 6e 64 20 65 78 70 72 65  eters] and expre
33ec0 73 73 69 6f 6e 73 20 63 6f 6d 70 6f 73 65 64 20  ssions composed 
33ed0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 2e 29 5e  from the same.)^
33ee0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
33ef0 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
33f00 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
33f10 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
33f20 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  ch.** the SQL fu
33f30 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
33f40 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
33f50 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
33f60 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
33f70 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73  , int N);.void s
33f80 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
33f90 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
33fa0 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64  xt*, int N, void
33fb0 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64  *, void (*)(void
33fc0 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *));.../*.** CAP
33fd0 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73  I3REF: Constants
33fe0 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61   Defining Specia
33ff0 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68  l Destructor Beh
34000 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73  avior.**.** Thes
34010 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61  e are special va
34020 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73  lues for the des
34030 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20  tructor that is 
34040 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65  passed in as the
34050 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65  .** final argume
34060 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  nt to routines l
34070 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ike [sqlite3_res
34080 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49  ult_blob()].  ^I
34090 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  f the destructor
340a0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
340b0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69  SQLITE_STATIC, i
340c0 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
340d0 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72   content pointer
340e0 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20   is constant.** 
340f0 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63  and will never c
34100 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20  hange.  It does 
34110 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64  not need to be d
34120 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a  estroyed.  ^The.
34130 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ** SQLITE_TRANSI
34140 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20  ENT value means 
34150 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
34160 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61   will likely cha
34170 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65  nge in.** the ne
34180 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68  ar future and th
34190 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64  at SQLite should
341a0 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72   make its own pr
341b0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a  ivate copy of.**
341c0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66   the content bef
341d0 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a  ore returning..*
341e0 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66  *.** The typedef
341f0 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f   is necessary to
34200 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f   work around pro
34210 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e  blems in certain
34220 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72  .** C++ compiler
34230 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f  s..*/.typedef vo
34240 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73  id (*sqlite3_des
34250 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f  tructor_type)(vo
34260 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51  id*);.#define SQ
34270 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20  LITE_STATIC     
34280 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
34290 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64  uctor_type)0).#d
342a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
342b0 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74  NSIENT   ((sqlit
342c0 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
342d0 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  pe)-1)../*.** CA
342e0 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20  PI3REF: Setting 
342f0 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e  The Result Of An
34300 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a   SQL Function.**
34310 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
34320 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74  es are used by t
34330 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e  he xFunc or xFin
34340 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  al callbacks tha
34350 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53  t.** implement S
34360 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
34370 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65   aggregates.  Se
34380 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  e.** [sqlite3_cr
34390 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
343a0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
343b0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
343c0 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69  )].** for additi
343d0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
343e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  ..**.** These fu
343f0 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72  nctions work ver
34400 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20  y much like the 
34410 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  [parameter bindi
34420 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ng] family of.**
34430 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20   functions used 
34440 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74  to bind values t
34450 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  o host parameter
34460 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74  s in prepared st
34470 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66  atements..** Ref
34480 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70  er to the [SQL p
34490 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65  arameter] docume
344a0 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69  ntation for addi
344b0 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
344c0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
344d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
344e0 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ob() interface s
344f0 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
34500 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
34510 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
34520 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
34530 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74   BLOB whose cont
34540 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a  ent is pointed.*
34550 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f  * to by the seco
34560 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
34570 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65   which is N byte
34580 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69  s long where N i
34590 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  s the.** third p
345a0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
345b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
345c0 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69  ult_zeroblob() i
345d0 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68  nterfaces set th
345e0 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
345f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
34600 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
34610 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e  to be a BLOB con
34620 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f  taining all zero
34630 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20  .** bytes and N 
34640 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77  bytes in size, w
34650 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61  here N is the va
34660 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70  lue of the 2nd p
34670 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
34680 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
34690 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74  ult_double() int
346a0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
346b0 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61  result from.** a
346c0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
346d0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
346e0 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20  o be a floating 
346f0 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63  point value spec
34700 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20  ified.** by its 
34710 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
34720 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34730 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
34740 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
34750 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e  lt_error16() fun
34760 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20  ctions.** cause 
34770 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  the implemented 
34780 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
34790 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69  throw an excepti
347a0 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  on..** ^SQLite u
347b0 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70  ses the string p
347c0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
347d0 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65  .** 2nd paramete
347e0 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73  r of sqlite3_res
347f0 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73  ult_error() or s
34800 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
34810 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68  ror16().** as th
34820 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72  e text of an err
34830 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51  or message.  ^SQ
34840 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20  Lite interprets 
34850 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
34860 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d  sage string from
34870 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34880 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38  error() as UTF-8
34890 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74  . ^SQLite.** int
348a0 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69  erprets the stri
348b0 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ng from sqlite3_
348c0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
348d0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61   as UTF-16 in na
348e0 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64  tive.** byte ord
348f0 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69  er.  ^If the thi
34900 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
34910 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
34920 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
34930 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
34940 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76  r16() is negativ
34950 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
34960 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72  kes as the error
34970 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20  .** message all 
34980 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20  text up through 
34990 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
349a0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66  haracter..** ^If
349b0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
349c0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
349d0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
349e0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  r.** sqlite3_res
349f0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
34a00 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68   non-negative th
34a10 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
34a20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74  that many.** byt
34a30 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
34a40 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  rs) from the 2nd
34a50 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68   parameter as th
34a60 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  e error message.
34a70 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34a80 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
34a90 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
34aa0 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
34ab0 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20  routines make a 
34ac0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
34ad0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
34ae0 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a  e text before.**
34af0 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48   they return.  H
34b00 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e  ence, the callin
34b10 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64  g function can d
34b20 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20  eallocate or.** 
34b30 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20  modify the text 
34b40 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72  after they retur
34b50 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  n without harm..
34b60 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34b70 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
34b80 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61  e() function cha
34b90 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63  nges the error c
34ba0 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  ode.** returned 
34bb0 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72  by SQLite as a r
34bc0 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f  esult of an erro
34bd0 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  r in a function.
34be0 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a    ^By default,.*
34bf0 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  * the error code
34c00 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   is SQLITE_ERROR
34c10 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74  .  ^A subsequent
34c20 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
34c30 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
34c40 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
34c50 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72  sult_error16() r
34c60 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20  esets the error 
34c70 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45  code to SQLITE_E
34c80 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  RROR..**.** ^The
34c90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34ca0 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69  error_toobig() i
34cb0 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
34cc0 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
34cd0 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69  an.** error indi
34ce0 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74  cating that a st
34cf0 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20  ring or BLOB is 
34d00 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72  too long to repr
34d10 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  esent..**.** ^Th
34d20 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
34d30 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69  _error_nomem() i
34d40 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
34d50 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
34d60 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69  an.** error indi
34d70 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65  cating that a me
34d80 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
34d90 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  failed..**.** ^T
34da0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
34db0 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63  t_int() interfac
34dc0 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
34dd0 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
34de0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
34df0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
34e00 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20  o be the 32-bit 
34e10 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
34e20 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e  * value given in
34e30 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e   the 2nd argumen
34e40 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  t..** ^The sqlit
34e50 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
34e60 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
34e70 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
34e80 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
34e90 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
34ea0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
34eb0 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  he 64-bit signed
34ec0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
34ed0 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
34ee0 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
34ef0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34f00 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e  result_null() in
34f10 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
34f20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
34f30 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
34f40 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
34f50 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e  tion to be NULL.
34f60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34f70 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
34f80 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ), sqlite3_resul
34f90 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73  t_text16(),.** s
34fa0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
34fb0 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71  xt16le(), and sq
34fc0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
34fd0 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63  t16be() interfac
34fe0 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65  es.** set the re
34ff0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
35000 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
35010 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
35020 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73  o be.** a text s
35030 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72  tring which is r
35040 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54  epresented as UT
35050 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69  F-8, UTF-16 nati
35060 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a  ve byte order,.*
35070 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20  * UTF-16 little 
35080 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31  endian, or UTF-1
35090 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65  6 big endian, re
350a0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
350b0 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65  SQLite takes the
350c0 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f   text result fro
350d0 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  m the applicatio
350e0 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e  n from.** the 2n
350f0 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  d parameter of t
35100 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
35110 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
35120 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33  es..** ^If the 3
35130 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
35140 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
35150 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
35160 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  ces.** is negati
35170 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ve, then SQLite 
35180 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78  takes result tex
35190 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70  t from the 2nd p
351a0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f  arameter.** thro
351b0 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
351c0 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
351d0 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72   ^If the 3rd par
351e0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
351f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
35200 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
35210 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
35220 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62  , then as many b
35230 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63  ytes (not charac
35240 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78  ters) of the tex
35250 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  t.** pointed to 
35260 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
35270 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61  eter are taken a
35280 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  s the applicatio
35290 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e  n-defined.** fun
352a0 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49  ction result.  I
352b0 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
352c0 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  ter is non-negat
352d0 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20  ive, then it.** 
352e0 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65  must be the byte
352f0 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65   offset into the
35300 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 74 68   string where th
35310 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72  e NUL terminator
35320 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72   would.** appear
35330 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 77   if the string w
35340 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61  here NUL termina
35350 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c  ted.  If any NUL
35360 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75   characters occu
35370 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69  r.** in the stri
35380 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f 66 66  ng at a byte off
35390 73 65 74 20 74 68 61 74 20 69 73 20 6c 65 73 73  set that is less
353a0 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20   than the value 
353b0 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61  of the 3rd.** pa
353c0 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68  rameter, then th
353d0 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
353e0 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20  ng will contain 
353f0 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e  embedded NULs an
35400 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  d the.** result 
35410 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f  of expressions o
35420 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69  perating on stri
35430 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64 64 65  ngs with embedde
35440 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69  d NULs is undefi
35450 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ned..** ^If the 
35460 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
35470 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
35480 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
35490 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
354a0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
354b0 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  s a non-NULL poi
354c0 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
354d0 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20  e calls that.** 
354e0 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20  function as the 
354f0 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68  destructor on th
35500 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
35510 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61  esult when it ha
35520 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73  s.** finished us
35530 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
35540 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
35550 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
35560 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35570 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
35580 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65   or to.** sqlite
35590 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
355a0 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
355b0 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41  stant SQLITE_STA
355c0 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  TIC, then SQLite
355d0 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74  .** assumes that
355e0 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f   the text or BLO
355f0 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63  B result is in c
35600 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e  onstant space an
35610 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f  d does not.** co
35620 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  py the content o
35630 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
35640 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72  nor call a destr
35650 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e  uctor on the con
35660 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20  tent.** when it 
35670 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69  has finished usi
35680 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
35690 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
356a0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
356b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
356c0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
356d0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
356e0 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
356f0 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
35700 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  t SQLITE_TRANSIE
35710 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74  NT.** then SQLit
35720 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
35730 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74  f the result int
35740 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64  o space obtained
35750 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73   from.** from [s
35760 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
35770 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72   before it retur
35780 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
35790 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
357a0 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
357b0 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
357c0 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
357d0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
357e0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63  nction to be a c
357f0 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72  opy the.** [unpr
35800 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
35810 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70  value] object sp
35820 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32  ecified by the 2
35830 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
35840 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  The.** sqlite3_r
35850 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
35860 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20  terface makes a 
35870 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
35880 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73  ite3_value].** s
35890 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69  o that the [sqli
358a0 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69  te3_value] speci
358b0 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61  fied in the para
358c0 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65  meter may change
358d0 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f   or.** be deallo
358e0 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69  cated after sqli
358f0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
35900 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f  () returns witho
35910 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b  ut harm..** ^A [
35920 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
35930 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
35940 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73  may always be us
35950 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b  ed where an.** [
35960 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
35970 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
35980 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73  t is required, s
35990 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64  o either.** kind
359a0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   of [sqlite3_val
359b0 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62  ue] object can b
359c0 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73  e used with this
359d0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
359e0 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69  * If these routi
359f0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66  nes are called f
35a00 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64  rom within the d
35a10 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a  ifferent thread.
35a20 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20  ** than the one 
35a30 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
35a40 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
35a50 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ed function that
35a60 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65   received.** the
35a70 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
35a80 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20  t] pointer, the 
35a90 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
35aa0 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73  fined..*/.void s
35ab0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
35ac0 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
35ad0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
35ae0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
35af0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
35b00 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
35b10 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
35b20 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f  xt*, double);.vo
35b30 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
35b40 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f  t_error(sqlite3_
35b50 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
35b60 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  char*, int);.voi
35b70 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
35b80 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33  _error16(sqlite3
35b90 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
35ba0 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f   void*, int);.vo
35bb0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
35bc0 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73  t_error_toobig(s
35bd0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
35be0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
35bf0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65  esult_error_nome
35c00 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  m(sqlite3_contex
35c10 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
35c20 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
35c30 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ode(sqlite3_cont
35c40 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
35c50 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35c60 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  int(sqlite3_cont
35c70 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
35c80 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35c90 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f  int64(sqlite3_co
35ca0 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
35cb0 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c  int64);.void sql
35cc0 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
35cd0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35ce0 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
35cf0 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c  _result_text(sql
35d00 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
35d10 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c  onst char*, int,
35d20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
35d30 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
35d40 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c  esult_text16(sql
35d50 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
35d60 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
35d70 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
35d80 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
35d90 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73  esult_text16le(s
35da0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
35db0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
35dc0 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
35dd0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
35de0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
35df0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35e00 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
35e10 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
35e20 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
35e30 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71  _result_value(sq
35e40 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
35e50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
35e60 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
35e70 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  sult_zeroblob(sq
35e80 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
35e90 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
35ea0 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20  API3REF: Define 
35eb0 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65  New Collating Se
35ec0 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54  quences.**.** ^T
35ed0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
35ee0 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d  dd, remove, or m
35ef0 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69  odify a [collati
35f00 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  on] associated.*
35f10 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  * with the [data
35f20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
35f30 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68   specified as th
35f40 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
35f50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
35f60 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  e of the collati
35f70 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  on is a UTF-8 st
35f80 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69  ring.** for sqli
35f90 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
35fa0 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  tion() and sqlit
35fb0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
35fc0 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20  ion_v2().** and 
35fd0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
35fe0 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
35ff0 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33  rder for sqlite3
36000 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
36010 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61  n16()..** ^Colla
36020 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20  tion names that 
36030 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63  compare equal ac
36040 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69  cording to [sqli
36050 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20  te3_strnicmp()] 
36060 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65  are.** considere
36070 64 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65  d to be the same
36080 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   name..**.** ^(T
36090 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
360a0 74 20 28 65 54 65 78 74 52 65 70 29 20 6d 75 73  t (eTextRep) mus
360b0 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20  t be one of the 
360c0 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75  constants:.** <u
360d0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
360e0 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69  TE_UTF8],.** <li
360f0 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  > [SQLITE_UTF16L
36100 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
36110 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a  ITE_UTF16BE],.**
36120 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
36130 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  F16], or.** <li>
36140 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
36150 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LIGNED]..** </ul
36160 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78  >)^.** ^The eTex
36170 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65  tRep argument de
36180 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63  termines the enc
36190 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73  oding of strings
361a0 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68   passed.** to th
361b0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
361c0 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78  tion callback, x
361d0 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68  Callback..** ^Th
361e0 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  e [SQLITE_UTF16]
361f0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46   and [SQLITE_UTF
36200 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75  16_ALIGNED] valu
36210 65 73 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a  es for eTextRep.
36220 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73  ** force strings
36230 20 74 6f 20 62 65 20 55 54 46 31 36 20 77 69 74   to be UTF16 wit
36240 68 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  h native byte or
36250 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  der..** ^The [SQ
36260 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
36270 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54  ED] value for eT
36280 65 78 74 52 65 70 20 66 6f 72 63 65 73 20 73 74  extRep forces st
36290 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a  rings to begin.*
362a0 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74  * on an even byt
362b0 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a  e address..**.**
362c0 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72 67   ^The fourth arg
362d0 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20  ument, pArg, is 
362e0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  an application d
362f0 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ata pointer that
36300 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68   is passed.** th
36310 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
36320 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
36330 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
36340 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a  ction callback..
36350 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
36360 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c   argument, xCall
36370 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74  back, is a point
36380 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  er to the collat
36390 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ing function..**
363a0 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61   ^Multiple colla
363b0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63  ting functions c
363c0 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64  an be registered
363d0 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
363e0 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68  name but.** with
363f0 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74   different eText
36400 52 65 70 20 70 61 72 61 6d 65 74 65 72 73 20 61  Rep parameters a
36410 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  nd SQLite will u
36420 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20  se whichever.** 
36430 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
36440 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
36450 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73  nt of data trans
36460 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49  formation..** ^I
36470 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20  f the xCallback 
36480 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c  argument is NULL
36490 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74   then the collat
364a0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a  ing function is.
364b0 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68  ** deleted.  ^Wh
364c0 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67  en all collating
364d0 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e   functions havin
364e0 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  g the same name 
364f0 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20  are deleted,.** 
36500 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69  that collation i
36510 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62  s no longer usab
36520 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  le..**.** ^The c
36530 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
36540 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  n callback is in
36550 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70  voked with a cop
36560 79 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a  y of the pArg .*
36570 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  * application da
36580 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77  ta pointer and w
36590 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20  ith two strings 
365a0 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  in the encoding 
365b0 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
365c0 74 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67  the eTextRep arg
365d0 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c  ument.  The coll
365e0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
365f0 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a  ust return an.**
36600 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 69 73   integer that is
36610 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c   negative, zero,
36620 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20   or positive.** 
36630 69 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72  if the first str
36640 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ing is less than
36650 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67  , equal to, or g
36660 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20  reater than the 
36670 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65  second,.** respe
36680 63 74 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c  ctively.  A coll
36690 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
366a0 75 73 74 20 61 6c 77 61 79 73 20 72 65 74 75 72  ust always retur
366b0 6e 20 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65  n the same answe
366c0 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73  r.** given the s
366d0 61 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20  ame inputs.  If 
366e0 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c  two or more coll
366f0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
36700 61 72 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a  are registered.*
36710 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f  * to the same co
36720 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73  llation name (us
36730 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20 65 54  ing different eT
36740 65 78 74 52 65 70 20 76 61 6c 75 65 73 29 20 74  extRep values) t
36750 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20  hen all.** must 
36760 67 69 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65  give an equivale
36770 6e 74 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69  nt answer when i
36780 6e 76 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69  nvoked with equi
36790 76 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a  valent strings..
367a0 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67  ** The collating
367b0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f   function must o
367c0 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  bey the followin
367d0 67 20 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72  g properties for
367e0 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20   all.** strings 
367f0 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a  A, B, and C:.**.
36800 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ol>.** <li> 
36810 49 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d  If A==B then B==
36820 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d  A..** <li> If A=
36830 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e  =B and B==C then
36840 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49   A==C..** <li> I
36850 66 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26  f A&lt;B THEN B&
36860 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66  gt;A..** <li> If
36870 20 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74   A&lt;B and B&lt
36880 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a  ;C then A&lt;C..
36890 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ol>.**.** I
368a0 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  f a collating fu
368b0 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79  nction fails any
368c0 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f   of the above co
368d0 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68  nstraints and th
368e0 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20  at.** collating 
368f0 66 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67  function is  reg
36900 69 73 74 65 72 65 64 20 61 6e 64 20 75 73 65 64  istered and used
36910 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
36920 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ior of SQLite.**
36930 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
36940 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
36950 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
36960 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69  on_v2() works li
36970 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ke sqlite3_creat
36980 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a  e_collation().**
36990 20 77 69 74 68 20 74 68 65 20 61 64 64 69 74 69   with the additi
369a0 6f 6e 20 74 68 61 74 20 74 68 65 20 78 44 65 73  on that the xDes
369b0 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  troy callback is
369c0 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67   invoked on pArg
369d0 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c   when.** the col
369e0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
369f0 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e  is deleted..** ^
36a00 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  Collating functi
36a10 6f 6e 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ons are deleted 
36a20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76  when they are ov
36a30 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65  erridden by late
36a40 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68  r.** calls to th
36a50 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61  e collation crea
36a60 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f  tion functions o
36a70 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64  r when the.** [d
36a80 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36a90 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73  on] is closed us
36aa0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  ing [sqlite3_clo
36ab0 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  se()]..**.** ^Th
36ac0 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62  e xDestroy callb
36ad0 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75  ack is <u>not</u
36ae0 3e 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20  > called if the 
36af0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
36b00 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
36b10 29 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73  ) function fails
36b20 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
36b30 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  that invoke.** s
36b40 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
36b50 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74  llation_v2() wit
36b60 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65  h a non-NULL xDe
36b70 73 74 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73  stroy argument s
36b80 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20  hould .** check 
36b90 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
36ba0 61 6e 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74  and dispose of t
36bb0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
36bc0 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ata pointer.** t
36bd0 68 65 6d 73 65 6c 76 65 73 20 72 61 74 68 65 72  hemselves rather
36be0 20 74 68 61 6e 20 65 78 70 65 63 74 69 6e 67 20   than expecting 
36bf0 53 51 4c 69 74 65 20 74 6f 20 64 65 61 6c 20 77  SQLite to deal w
36c00 69 74 68 20 69 74 20 66 6f 72 20 74 68 65 6d 2e  ith it for them.
36c10 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 69 66 66  .** This is diff
36c20 65 72 65 6e 74 20 66 72 6f 6d 20 65 76 65 72 79  erent from every
36c30 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
36c40 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 69 6e  terface.  The in
36c50 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20  consistency .** 
36c60 69 73 20 75 6e 66 6f 72 74 75 6e 61 74 65 20 62  is unfortunate b
36c70 75 74 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61  ut cannot be cha
36c80 6e 67 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  nged without bre
36c90 61 6b 69 6e 67 20 62 61 63 6b 77 61 72 64 73 20  aking backwards 
36ca0 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
36cb0 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  y..**.** See als
36cc0 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  o:  [sqlite3_col
36cd0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d  lation_needed()]
36ce0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f   and [sqlite3_co
36cf0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
36d00 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
36d10 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
36d20 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a  tion(.  sqlite3*
36d30 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
36d40 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
36d50 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
36d60 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78   *pArg,.  int(*x
36d70 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
36d80 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
36d90 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
36da0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
36db0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
36dc0 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  v2(.  sqlite3*, 
36dd0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
36de0 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
36df0 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a  xtRep, .  void *
36e00 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  pArg,.  int(*xCo
36e10 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
36e20 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
36e30 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20  ,const void*),. 
36e40 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
36e50 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73  (void*).);.int s
36e60 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
36e70 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  llation16(.  sql
36e80 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
36e90 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69  void *zName,.  i
36ea0 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
36eb0 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e  void *pArg,.  in
36ec0 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
36ed0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
36ee0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
36ef0 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*).);../*.** CA
36f00 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f  PI3REF: Collatio
36f10 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63  n Needed Callbac
36f20 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f  ks.**.** ^To avo
36f30 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67  id having to reg
36f40 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74  ister all collat
36f50 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65  ion sequences be
36f60 66 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a  fore a database.
36f70 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20  ** can be used, 
36f80 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63  a single callbac
36f90 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  k function may b
36fa0 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74  e registered wit
36fb0 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  h the.** [databa
36fc0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
36fd0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
36fe0 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e  never an undefin
36ff0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20  ed collation.** 
37000 73 65 71 75 65 6e 63 65 20 69 73 20 72 65 71 75  sequence is requ
37010 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ired..**.** ^If 
37020 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
37030 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
37040 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
37050 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
37060 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20  API,.** then it 
37070 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61  is passed the na
37080 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64  mes of undefined
37090 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
370a0 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a  nces as strings.
370b0 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54  ** encoded in UT
370c0 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33  F-8. ^If sqlite3
370d0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
370e0 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a  d16() is used,.*
370f0 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20  * the names are 
37100 70 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36  passed as UTF-16
37110 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69   in machine nati
37120 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
37130 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74  * ^A call to eit
37140 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70  her function rep
37150 6c 61 63 65 73 20 74 68 65 20 65 78 69 73 74 69  laces the existi
37160 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65  ng collation-nee
37170 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ded callback..**
37180 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63  .** ^(When the c
37190 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
371a0 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72  ed, the first ar
371b0 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73  gument passed is
371c0 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68   a copy.** of th
371d0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
371e0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  t to sqlite3_col
371f0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
37200 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
37210 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
37220 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ().  The second 
37230 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
37240 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
37250 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69  ection.  The thi
37260 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  rd argument is o
37270 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54  ne of [SQLITE_UT
37280 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  F8], [SQLITE_UTF
37290 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51  16BE],.** or [SQ
372a0 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69  LITE_UTF16LE], i
372b0 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f  ndicating the mo
372c0 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72  st desirable for
372d0 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  m of the collati
372e0 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66  on.** sequence f
372f0 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64  unction required
37300 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
37310 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
37320 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  ame of the.** re
37330 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  quired collation
37340 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a   sequence.)^.**.
37350 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
37360 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
37370 72 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73  register the des
37380 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75  ired collation u
37390 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
373a0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
373b0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  n()], [sqlite3_c
373c0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
373d0 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
373e0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
373f0 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a  ation_v2()]..*/.
37400 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  int sqlite3_coll
37410 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20  ation_needed(.  
37420 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
37430 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76  d*, .  void(*)(v
37440 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
37450 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
37460 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73   char*).);.int s
37470 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
37480 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c  _needed16(.  sql
37490 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
374a0 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
374b0 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
374c0 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69  extRep,const voi
374d0 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53  d*).);..#ifdef S
374e0 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a  QLITE_HAS_CODEC.
374f0 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68  /*.** Specify th
37500 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63  e key for an enc
37510 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e  rypted database.
37520 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73    This routine s
37530 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c  hould be.** call
37540 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73  ed right after s
37550 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a  qlite3_open()..*
37560 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f  *.** The code to
37570 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20   implement this 
37580 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c  API is not avail
37590 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c  able in the publ
375a0 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66  ic release.** of
375b0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20   SQLite..*/.int 
375c0 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73  sqlite3_key(.  s
375d0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
375e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
375f0 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   Database to be 
37600 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e  rekeyed */.  con
37610 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
37620 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
37630 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 69 6e 74  he key */.);.int
37640 20 73 71 6c 69 74 65 33 5f 6b 65 79 5f 76 32 28   sqlite3_key_v2(
37650 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
37660 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37670 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
37680 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
37690 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
376a0 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 20 20  Name,           
376b0 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64  /* Name of the d
376c0 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
376d0 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
376e0 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
376f0 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a  he key */.);../*
37700 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b  .** Change the k
37710 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61  ey on an open da
37720 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20  tabase.  If the 
37730 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65  current database
37740 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79   is not.** encry
37750 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69  pted, this routi
37760 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20  ne will encrypt 
37770 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20  it.  If pNew==0 
37780 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a  or nNew==0, the.
37790 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64  ** database is d
377a0 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ecrypted..**.** 
377b0 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
377c0 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
377d0 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
377e0 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
377f0 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
37800 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
37810 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69  e3_rekey(.  sqli
37820 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
37830 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
37840 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b  tabase to be rek
37850 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  eyed */.  const 
37860 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20  void *pKey, int 
37870 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20  nKey     /* The 
37880 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 69 6e  new key */.);.in
37890 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 5f  t sqlite3_rekey_
378a0 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
378b0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
378c0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
378d0 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a   to be rekeyed *
378e0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
378f0 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20  zDbName,        
37900 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
37910 65 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  e database */.  
37920 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79  const void *pKey
37930 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f  , int nKey     /
37940 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f  * The new key */
37950 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  .);../*.** Speci
37960 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f  fy the activatio
37970 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45 45 20  n key for a SEE 
37980 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73  database.  Unles
37990 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c  s .** activated,
379a0 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 45 45   none of the SEE
379b0 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77   routines will w
379c0 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ork..*/.void sql
379d0 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 73 65  ite3_activate_se
379e0 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  e(.  const char 
379f0 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20  *zPassPhrase    
37a00 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f      /* Activatio
37a10 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23  n phrase */.);.#
37a20 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 53 51  endif..#ifdef SQ
37a30 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f  LITE_ENABLE_CERO
37a40 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  D./*.** Specify 
37a50 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b  the activation k
37a60 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44 20 64  ey for a CEROD d
37a70 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73  atabase.  Unless
37a80 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20   .** activated, 
37a90 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45 52 4f  none of the CERO
37aa0 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20  D routines will 
37ab0 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  work..*/.void sq
37ac0 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 63  lite3_activate_c
37ad0 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63 68  erod(.  const ch
37ae0 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20  ar *zPassPhrase 
37af0 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61         /* Activa
37b00 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29  tion phrase */.)
37b10 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ;.#endif../*.** 
37b20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e  CAPI3REF: Suspen
37b30 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20  d Execution For 
37b40 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a  A Short Time.**.
37b50 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  ** The sqlite3_s
37b60 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20  leep() function 
37b70 63 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65  causes the curre
37b80 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73  nt thread to sus
37b90 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a  pend execution.*
37ba0 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61  * for at least a
37bb0 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69   number of milli
37bc0 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65  seconds specifie
37bd0 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74  d in its paramet
37be0 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  er..**.** If the
37bf0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
37c00 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f  m does not suppo
37c10 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74  rt sleep request
37c20 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73  s with.** millis
37c30 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c  econd time resol
37c40 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ution, then the 
37c50 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75  time will be rou
37c60 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68  nded up to.** th
37c70 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64  e nearest second
37c80 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  . The number of 
37c90 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
37ca0 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a  sleep actually.*
37cb0 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d  * requested from
37cc0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
37cd0 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65  ystem is returne
37ce0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  d..**.** ^SQLite
37cf0 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73   implements this
37d00 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 63 61   interface by ca
37d10 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70  lling the xSleep
37d20 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20  ().** method of 
37d30 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
37d40 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
37d50 2e 20 20 49 66 20 74 68 65 20 78 53 6c 65 65 70  .  If the xSleep
37d60 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20  () method.** of 
37d70 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
37d80 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74  is not implement
37d90 65 64 20 63 6f 72 72 65 63 74 6c 79 2c 20 6f 72  ed correctly, or
37da0 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64   not implemented
37db0 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e   at.** all, then
37dc0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
37dd0 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29   sqlite3_sleep()
37de0 20 6d 61 79 20 64 65 76 69 61 74 65 20 66 72 6f   may deviate fro
37df0 6d 20 74 68 65 20 64 65 73 63 72 69 70 74 69 6f  m the descriptio
37e00 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72 65 76  n.** in the prev
37e10 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 73 2e  ious paragraphs.
37e20 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
37e30 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  sleep(int);../*.
37e40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
37e50 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20  e Of The Folder 
37e60 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72  Holding Temporar
37e70 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28  y Files.**.** ^(
37e80 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76  If this global v
37e90 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20  ariable is made 
37ea0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  to point to a st
37eb0 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a  ring which is.**
37ec0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66   the name of a f
37ed0 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69  older (a.k.a. di
37ee0 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61  rectory), then a
37ef0 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ll temporary fil
37f00 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  es.** created by
37f10 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69   SQLite when usi
37f20 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73  ng a built-in [s
37f30 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53  qlite3_vfs | VFS
37f40 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61  ].** will be pla
37f50 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65  ced in that dire
37f60 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74 68  ctory.)^  ^If th
37f70 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69  is variable.** i
37f80 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
37f90 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65  , then SQLite pe
37fa0 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20  rforms a search 
37fb0 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61  for an appropria
37fc0 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
37fd0 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a  file directory..
37fe0 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
37ff0 6e 73 20 61 72 65 20 73 74 72 6f 6e 67 6c 79 20  ns are strongly 
38000 64 69 73 63 6f 75 72 61 67 65 64 20 66 72 6f 6d  discouraged from
38010 20 75 73 69 6e 67 20 74 68 69 73 20 67 6c 6f 62   using this glob
38020 61 6c 20 76 61 72 69 61 62 6c 65 2e 0a 2a 2a 20  al variable..** 
38030 49 74 20 69 73 20 72 65 71 75 69 72 65 64 20 74  It is required t
38040 6f 20 73 65 74 20 61 20 74 65 6d 70 6f 72 61 72  o set a temporar
38050 79 20 66 6f 6c 64 65 72 20 6f 6e 20 57 69 6e 64  y folder on Wind
38060 6f 77 73 20 52 75 6e 74 69 6d 65 20 28 57 69 6e  ows Runtime (Win
38070 52 54 29 2e 0a 2a 2a 20 42 75 74 20 66 6f 72 20  RT)..** But for 
38080 61 6c 6c 20 6f 74 68 65 72 20 70 6c 61 74 66 6f  all other platfo
38090 72 6d 73 2c 20 69 74 20 69 73 20 68 69 67 68 6c  rms, it is highl
380a0 79 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  y recommended th
380b0 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  at applications.
380c0 2a 2a 20 6e 65 69 74 68 65 72 20 72 65 61 64 20  ** neither read 
380d0 6e 6f 72 20 77 72 69 74 65 20 74 68 69 73 20 76  nor write this v
380e0 61 72 69 61 62 6c 65 2e 20 20 54 68 69 73 20 67  ariable.  This g
380f0 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69  lobal variable i
38100 73 20 61 20 72 65 6c 69 63 0a 2a 2a 20 74 68 61  s a relic.** tha
38110 74 20 65 78 69 73 74 73 20 66 6f 72 20 62 61 63  t exists for bac
38120 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
38130 6c 69 74 79 20 6f 66 20 6c 65 67 61 63 79 20 61  lity of legacy a
38140 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20  pplications and 
38150 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 76 6f  should.** be avo
38160 69 64 65 64 20 69 6e 20 6e 65 77 20 70 72 6f 6a  ided in new proj
38170 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69  ects..**.** It i
38180 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65  s not safe to re
38190 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ad or modify thi
381a0 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f  s variable in mo
381b0 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74  re than one.** t
381c0 68 72 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e  hread at a time.
381d0 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65    It is not safe
381e0 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69   to read or modi
381f0 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
38200 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61  .** if a [databa
38210 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
38220 73 20 62 65 69 6e 67 20 75 73 65 64 20 61 74 20  s being used at 
38230 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e  the same time in
38240 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74   a separate.** t
38250 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20  hread..** It is 
38260 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68  intended that th
38270 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73  is variable be s
38280 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61  et once.** as pa
38290 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e  rt of process in
382a0 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
382b0 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69   before any SQLi
382c0 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  te interface.** 
382d0 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65  routines have be
382e0 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68  en called and th
382f0 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
38300 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65   remain unchange
38310 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e  d.** thereafter.
38320 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d  .**.** ^The [tem
38330 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
38340 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f  y pragma] may mo
38350 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
38360 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20  le and cause.** 
38370 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d  it to point to m
38380 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
38390 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
383a0 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d  loc].  ^Furtherm
383b0 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d  ore,.** the [tem
383c0 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
383d0 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73  y pragma] always
383e0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e   assumes that an
383f0 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74  y string.** that
38400 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 70   this variable p
38410 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64  oints to is held
38420 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   in memory obtai
38430 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71  ned from .** [sq
38440 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e  lite3_malloc] an
38450 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79  d the pragma may
38460 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65   attempt to free
38470 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20   that memory.** 
38480 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
38490 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20  ree]..** Hence, 
384a0 69 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  if this variable
384b0 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72   is modified dir
384c0 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74  ectly, either it
384d0 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61   should be.** ma
384e0 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20  de NULL or made 
384f0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f  to point to memo
38500 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
38510 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
38520 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65  ].** or else the
38530 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d   use of the [tem
38540 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
38550 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64  y pragma] should
38560 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 20   be avoided..** 
38570 45 78 63 65 70 74 20 77 68 65 6e 20 72 65 71 75  Except when requ
38580 65 73 74 65 64 20 62 79 20 74 68 65 20 5b 74 65  ested by the [te
38590 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
385a0 72 79 20 70 72 61 67 6d 61 5d 2c 20 53 51 4c 69  ry pragma], SQLi
385b0 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 66  te.** does not f
385c0 72 65 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74  ree the memory t
385d0 68 61 74 20 73 71 6c 69 74 65 33 5f 74 65 6d 70  hat sqlite3_temp
385e0 5f 64 69 72 65 63 74 6f 72 79 20 70 6f 69 6e 74  _directory point
385f0 73 20 74 6f 2e 20 20 49 66 0a 2a 2a 20 74 68 65  s to.  If.** the
38600 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 61 6e   application wan
38610 74 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 74  ts that memory t
38620 6f 20 62 65 20 66 72 65 65 64 2c 20 69 74 20 6d  o be freed, it m
38630 75 73 74 20 64 6f 0a 2a 2a 20 73 6f 20 69 74 73  ust do.** so its
38640 65 6c 66 2c 20 74 61 6b 69 6e 67 20 63 61 72 65  elf, taking care
38650 20 74 6f 20 6f 6e 6c 79 20 64 6f 20 73 6f 20 61   to only do so a
38660 66 74 65 72 20 61 6c 6c 20 5b 64 61 74 61 62 61  fter all [databa
38670 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a  se connection].*
38680 2a 20 6f 62 6a 65 63 74 73 20 68 61 76 65 20 62  * objects have b
38690 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  een destroyed..*
386a0 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
386b0 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20  Windows Runtime 
386c0 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
386d0 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74  temporary direct
386e0 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a  ory must be set.
386f0 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ** prior to call
38700 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  ing [sqlite3_ope
38710 6e 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  n] or [sqlite3_o
38720 70 65 6e 5f 76 32 5d 2e 20 20 4f 74 68 65 72 77  pen_v2].  Otherw
38730 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20  ise, various.** 
38740 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65  features that re
38750 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66  quire the use of
38760 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73   temporary files
38770 20 6d 61 79 20 66 61 69 6c 2e 20 20 48 65 72 65   may fail.  Here
38780 20 69 73 20 61 6e 0a 2a 2a 20 65 78 61 6d 70 6c   is an.** exampl
38790 65 20 6f 66 20 68 6f 77 20 74 6f 20 64 6f 20 74  e of how to do t
387a0 68 69 73 20 75 73 69 6e 67 20 43 2b 2b 20 77 69  his using C++ wi
387b0 74 68 20 74 68 65 20 57 69 6e 64 6f 77 73 20 52  th the Windows R
387c0 75 6e 74 69 6d 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62  untime:.**.** <b
387d0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
387e0 2a 2a 20 4c 50 43 57 53 54 52 20 7a 50 61 74 68  ** LPCWSTR zPath
387f0 20 3d 20 57 69 6e 64 6f 77 73 3a 3a 53 74 6f 72   = Windows::Stor
38800 61 67 65 3a 3a 41 70 70 6c 69 63 61 74 69 6f 6e  age::Appli